@caseyharalson/orrery 0.7.1

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

@@ -0,0 +1,244 @@
+---
+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).
+  Ask "what if" questions, trace dependencies, and build intuition about what you're building.
+---
+
+# Simulate Skill
+
+## When to Use
+
+Use this skill when you have a plan and want to **think through it** before executing. Simulate is a thinking partner that helps you interrogate the plan, explore implications, and build confidence in your approach.
+
+**Triggers:**
+
+- "Let's think through this plan before we start"
+- "What if..." questions about the plan
+- Uncertainty about whether the plan is right
+- Want to understand implications before committing
+- "Walk me through this plan"
+
+**Skip if:**
+
+- No plan exists yet (use Discovery first)
+- Ready to execute and confident in the approach
+- Need to actually modify the plan (use Discovery skill instead)
+
+---
+
+## How to Do It
+
+### Step 1: Load the Plan
+
+Read and internalize the plan structure:
+
+- Parse the YAML to understand steps, dependencies, criteria
+- Note the outcomes (what success looks like)
+- Identify risks and constraints mentioned in `risk_notes`
+- Map the dependency graph (what blocks what)
+
+Announce what you've loaded:
+
+```
+I've loaded the [plan name]. It has [N] steps delivering [outcomes].
+The critical path runs through [key steps]. What would you like to explore?
+```
+
+### Step 2: Enter Dialogue Mode
+
+Answer questions conversationally. Don't wait for specific commands—respond to natural questions about the plan.
+
+For each question:
+
+1. Identify which part of the plan is relevant
+2. Trace implications through the dependency graph
+3. Reference specific steps, criteria, or requirements
+4. Suggest follow-up questions if appropriate
+
+### Step 3: Stay Read-Only
+
+Never modify the plan file. If the user wants to make changes based on the simulation:
+
+- Summarize the proposed changes
+- Suggest exiting simulate and using the Discovery skill to revise
+- Offer to continue exploring other aspects first
+
+---
+
+## Question Types
+
+Guide users toward productive exploration. Handle these question patterns:
+
+### Dependency Questions
+
+- "What depends on step X?"
+- "What's blocking the frontend work?"
+- "If step 3 slips, what else is affected?"
+- "Can we do A and B in parallel?"
+
+**How to answer:** Trace the `deps` field. Show upstream (what this depends on) and downstream (what depends on this) relationships.
+
+### Scope Questions
+
+- "Do we really need all of this for an MVP?"
+- "Which steps deliver the core value?"
+- "What could we cut without breaking the outcomes?"
+- "What's the simplest version that works?"
+
+**How to answer:** Connect steps back to outcomes. Identify which steps are essential vs. nice-to-have based on the criteria and requirements.
+
+### Risk Questions
+
+- "What's the riskiest step?"
+- "What happens if the API integration takes longer than expected?"
+- "Where are we most likely to get stuck?"
+- "What could go wrong?"
+
+**How to answer:** Reference `risk_notes` from the plan. Consider steps with many dependencies (high blast radius) or external integrations (uncertainty).
+
+### Alternative Questions
+
+- "Could we do this a different way?"
+- "What if we used X instead of Y?"
+- "Is there a simpler path?"
+- "What would change if we...?"
+
+**How to answer:** Reason through how the alternative would affect other steps. Note which requirements or criteria would need to change.
+
+### Validation Questions
+
+- "Does this plan actually deliver what we said we wanted?"
+- "Are there gaps between the outcomes and the steps?"
+- "Have we forgotten anything?"
+- "Is this plan complete?"
+
+**How to answer:** Map steps to outcomes. Check if every outcome has steps that deliver it. Look for implicit requirements that aren't captured.
+
+---
+
+## Response Style
+
+### Be Conversational
+
+Don't produce formal reports. Think out loud with the user.
+
+**Bad:** "Analysis complete. The dependency graph shows..."
+**Good:** "Let me trace that through. Step 3 needs step 2's output, so if you skip 2..."
+
+### Trace Implications
+
+Walk through cause and effect chains.
+
+**Example:**
+
+> "If you skip the caching step, the trends endpoint will still work, but you won't meet the 200ms response time criterion. That affects the 'responsive dashboard' requirement in step 4. The risk note mentions 'API response time under load'—without caching, that risk is higher."
+
+### Ask Follow-Up Questions
+
+Understand the user's underlying concern.
+
+**Example:**
+
+> "Are you asking because you're worried about scope, or because you're not sure caching is the right approach?"
+
+### Reference the Plan
+
+Quote specific steps, criteria, and requirements. Don't make up constraints.
+
+**Example:**
+
+> "Step 2 specifies 'Cache responses for 1 hour' in requirement 3. That's what we'd be cutting."
+
+### Stay Grounded
+
+Only discuss what's in the plan. If asked about implementation details not covered, acknowledge the gap.
+
+**Example:**
+
+> "The plan doesn't specify which caching library to use—that's an implementation detail for the Execute phase."
+
+---
+
+## Example Dialogue
+
+```
+User: /simulate .agent-work/plans/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."
+
+The critical path is: API endpoint (step 2) → Caching (step 3) → Visualization (step 1).
+Export functionality (steps 5-6) can run in parallel once the API is ready.
+
+What would you like to explore?
+
+User: What if we skip the caching step?
+
+Agent: Step 3 (Query result caching) is a dependency for step 1 (Trend
+visualization). If you skip caching:
+
+- The trends endpoint will work, but may be slow (no 200ms target)
+- Step 1's "responsive dashboard" criterion becomes harder to meet
+- The risk note mentions "API response time under load"—without caching,
+  this risk materializes
+
+The core functionality would work, but you'd be shipping a slower experience.
+Is performance a hard requirement, or could caching be a fast-follow?
+
+User: Could we do a simpler version of caching?
+
+Agent: The plan currently specifies "Cache responses for 1 hour" in
+requirement 3 of step 3. Some simpler approaches:
+
+- In-memory cache (no Redis)—simpler but lost on restart
+- Shorter TTL (5 min)—less stale data, more cache misses
+- Cache only the expensive aggregations, not full responses
+
+None of these are in the current plan. If you want to explore a variant,
+we should exit simulate and revise the plan. Want to keep exploring first,
+or make changes now?
+
+User: Let's keep exploring. What's the riskiest step?
+
+Agent: Looking at risk_notes and dependencies, I'd say step 2 (Create trends
+API endpoint) is the riskiest:
+
+1. It has the most downstream dependencies—steps 1, 3, 5, and 6 all need it
+2. The risk note mentions "complex date aggregation logic"
+3. If the data model doesn't support efficient range queries, you'll discover
+   it here
+
+Step 3 (caching) is the second riskiest because it affects performance
+criteria across multiple steps.
+
+Want me to trace what happens if step 2 takes longer than expected?
+```
+
+---
+
+## Boundaries
+
+### Read-Only
+
+Simulate never modifies the plan. The plan file is treated as immutable during simulation. If changes are needed, the user should exit and use the Discovery skill.
+
+### Plan-Scoped
+
+Answer based on plan content, not general coding advice. If asked "how should I implement caching?", redirect: "That's an Execute phase decision. In this plan, the caching step specifies [requirements]. Do you want to explore whether those requirements are right?"
+
+### Suggests But Doesn't Decide
+
+Present options and implications, but let the user decide what to do. Don't say "you should cut this step"—instead say "if you cut this step, here's what changes."
+
+---
+
+## Common Pitfalls
+
+- **Inventing constraints:** Only discuss what's in the plan. Don't assume requirements or risks that aren't documented.
+- **Formal analysis mode:** Keep it conversational. Users want to think out loud, not receive a report.
+- **Skipping the dependency trace:** When asked "what if we skip X?", always trace through what depends on X. Don't just say "it would be faster."
+- **Forgetting to reference the plan:** Quote specific steps and criteria. Vague answers aren't helpful.
+- **Trying to modify the plan:** If changes are needed, explicitly suggest exiting simulate mode. Don't try to "fix" the plan inline.
+- **No follow-up questions:** Understand what the user is really asking. A question about scope might really be about risk, or vice versa.

package/bin/orrery.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { run } = require("../lib/cli");
+
+run(process.argv);

package/lib/cli/commands/help.js

@@ -0,0 +1,21 @@
+module.exports = function registerHelpCommand(program) {
+  program
+    .command("help [command]")
+    .description("Display help for a command")
+    .action((command) => {
+      if (!command) {
+        program.outputHelp();
+        return;
+      }
+
+      const subcommand = program.commands.find((cmd) => cmd.name() === command);
+      if (!subcommand) {
+        console.error(`Unknown command: ${command}`);
+        program.outputHelp();
+        process.exitCode = 1;
+        return;
+      }
+
+      subcommand.outputHelp();
+    });
+};

package/lib/cli/commands/ingest-plan.js

@@ -0,0 +1,56 @@
+const fs = require("fs");
+const path = require("path");
+
+const { getPlansDir } = require("../../utils/paths");
+const { validatePlanStructure } = require("./validate-plan");
+
+module.exports = function registerIngestPlanCommand(program) {
+  program
+    .command("ingest-plan")
+    .description("Validate and import a plan file into the plans directory")
+    .argument("<file>", "Path to the plan file to ingest")
+    .option("--force", "Overwrite existing plan file if it exists")
+    .action((file, options) => {
+      const sourcePath = path.resolve(file);
+
+      if (!fs.existsSync(sourcePath)) {
+        console.error(`File not found: ${file}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const { errors, warnings } = validatePlanStructure(sourcePath);
+
+      if (errors.length > 0) {
+        console.error("Validation errors:\n");
+        errors.forEach((err) => console.error(`  - ${err}`));
+        console.error();
+        process.exitCode = 2;
+        return;
+      }
+
+      if (warnings.length > 0) {
+        console.warn("Warnings:\n");
+        warnings.forEach((warn) => console.warn(`  - ${warn}`));
+        console.warn();
+      }
+
+      const plansDir = getPlansDir();
+      if (!fs.existsSync(plansDir)) {
+        fs.mkdirSync(plansDir, { recursive: true });
+      }
+
+      const fileName = path.basename(sourcePath);
+      const destPath = path.join(plansDir, fileName);
+
+      if (fs.existsSync(destPath) && !options.force) {
+        console.error(`Plan already exists: ${destPath}`);
+        console.error("Use --force to overwrite");
+        process.exitCode = 1;
+        return;
+      }
+
+      fs.copyFileSync(sourcePath, destPath);
+      console.log(`Plan ingested: ${destPath}`);
+    });
+};

package/lib/cli/commands/init.js

@@ -0,0 +1,21 @@
+const { installSkillsAction } = require("./install-skills");
+
+function initAction(options) {
+  console.log("Initializing Orrery...\n");
+
+  // Install skills to detected agents
+  installSkillsAction(options);
+}
+
+module.exports = function registerInitCommand(program) {
+  program
+    .command("init")
+    .description("Initialize Orrery: install skills to detected agents")
+    .option(
+      "--agent <agent>",
+      "Target agent (claude|codex|gemini|all); defaults to auto-detect"
+    )
+    .option("--force", "Overwrite existing skills")
+    .option("--dry-run", "Show what would be copied without writing files")
+    .action(initAction);
+};

package/lib/cli/commands/install-devcontainer.js

@@ -0,0 +1,97 @@
+const fs = require("fs");
+const path = require("path");
+
+function getProjectRoot() {
+  return path.join(__dirname, "..", "..", "..");
+}
+
+function getSourceDevcontainerDir() {
+  return path.join(getProjectRoot(), ".devcontainer.example");
+}
+
+function copyDirectory(src, dest, options = {}) {
+  const { dryRun = false } = options;
+  const copiedFiles = [];
+
+  if (!dryRun) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      const subFiles = copyDirectory(srcPath, destPath, options);
+      copiedFiles.push(...subFiles);
+    } else {
+      if (!dryRun) {
+        fs.copyFileSync(srcPath, destPath);
+      }
+      copiedFiles.push(destPath);
+    }
+  }
+
+  return copiedFiles;
+}
+
+module.exports = function registerInstallDevcontainerCommand(program) {
+  program
+    .command("install-devcontainer")
+    .description("Copy the orrery devcontainer to a target directory")
+    .argument("[target]", "Target directory", process.cwd())
+    .option("--force", "Overwrite existing devcontainer")
+    .option("--dry-run", "Show what would be copied without writing files")
+    .action((target, options) => {
+      const sourceDir = getSourceDevcontainerDir();
+      if (!fs.existsSync(sourceDir)) {
+        console.error(`Source .devcontainer not found: ${sourceDir}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const targetDir = path.resolve(target);
+      const destDevcontainer = path.join(targetDir, ".devcontainer");
+
+      if (!fs.existsSync(targetDir)) {
+        console.error(`Target directory does not exist: ${targetDir}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (fs.existsSync(destDevcontainer)) {
+        if (!options.force) {
+          console.error(
+            `Devcontainer already exists at: ${destDevcontainer}\nUse --force to overwrite.`
+          );
+          process.exitCode = 1;
+          return;
+        }
+        console.log("Overwriting existing devcontainer (--force).");
+      }
+
+      if (options.dryRun) {
+        console.log("Dry run enabled. No files will be written.");
+      }
+
+      console.log(`Source: ${sourceDir}`);
+      console.log(`Target: ${destDevcontainer}`);
+
+      try {
+        const copiedFiles = copyDirectory(sourceDir, destDevcontainer, {
+          dryRun: options.dryRun
+        });
+
+        console.log(
+          `${options.dryRun ? "Would copy" : "Copied"} ${copiedFiles.length} file${
+            copiedFiles.length === 1 ? "" : "s"
+          }.`
+        );
+      } catch (error) {
+        console.error(`Failed to copy devcontainer: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+};

package/lib/cli/commands/install-skills.js

@@ -0,0 +1,182 @@
+const fs = require("fs");
+const path = require("path");
+
+const {
+  detectInstalledAgents,
+  getAgentSkillsDir
+} = require("../../utils/agent-detector");
+const { copySkills } = require("../../utils/skill-copier");
+
+const SUPPORTED_AGENTS = ["claude", "codex", "gemini"];
+
+function getSourceSkillsDir() {
+  return path.join(__dirname, "..", "..", "..", "agent", "skills");
+}
+
+function listSkillDirectories(sourceDir) {
+  if (!fs.existsSync(sourceDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(sourceDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function resolveRequestedAgents(agentOption) {
+  if (!agentOption) {
+    const detected = detectInstalledAgents();
+    return {
+      agents: detected,
+      reason:
+        detected.length === 0
+          ? "No installed agents detected. Use --agent to override."
+          : null
+    };
+  }
+
+  const normalized = agentOption.toLowerCase();
+  if (normalized === "all") {
+    const detected = detectInstalledAgents();
+    return {
+      agents: detected,
+      reason:
+        detected.length === 0
+          ? "No installed agents detected. Create an agent directory first."
+          : null
+    };
+  }
+
+  if (!SUPPORTED_AGENTS.includes(normalized)) {
+    return {
+      agents: [],
+      reason: `Unknown agent: ${agentOption}. Expected one of ${SUPPORTED_AGENTS.join(
+        ", "
+      )} or "all".`
+    };
+  }
+
+  return { agents: [normalized], reason: null };
+}
+
+function filterMissingAgents(agents) {
+  const available = [];
+  const missing = [];
+
+  for (const agent of agents) {
+    const skillsDir = getAgentSkillsDir(agent);
+    if (!skillsDir) {
+      missing.push({ agent, reason: "Unsupported agent." });
+      continue;
+    }
+
+    const agentRoot = path.dirname(skillsDir);
+    if (!fs.existsSync(agentRoot)) {
+      missing.push({
+        agent,
+        reason: `Agent directory not found: ${agentRoot}`
+      });
+      continue;
+    }
+
+    available.push(agent);
+  }
+
+  return { available, missing };
+}
+
+function installSkillsAction(options) {
+  const sourceDir = getSourceSkillsDir();
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`Source skills directory not found: ${sourceDir}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const skills = listSkillDirectories(sourceDir);
+  if (skills.length === 0) {
+    console.error(`No skills found in: ${sourceDir}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { agents, reason } = resolveRequestedAgents(options.agent);
+  if (reason && agents.length === 0) {
+    console.warn(reason);
+    if (options.agent && options.agent !== "all") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const { available, missing } = filterMissingAgents(agents);
+  if (missing.length > 0) {
+    for (const entry of missing) {
+      console.warn(`Skipping ${entry.agent}: ${entry.reason}`);
+    }
+  }
+
+  if (available.length === 0) {
+    console.warn("No valid agent targets found.");
+    return;
+  }
+
+  console.log(
+    `Installing ${skills.length} skill${
+      skills.length === 1 ? "" : "s"
+    }: ${skills.join(", ")}`
+  );
+  if (options.dryRun) {
+    console.log("Dry run enabled. No files will be written.");
+  }
+
+  let totalFiles = 0;
+
+  for (const agent of available) {
+    const targetDir = getAgentSkillsDir(agent);
+    console.log(`\nAgent: ${agent}`);
+    console.log(`Target: ${targetDir}`);
+
+    try {
+      const copiedFiles = copySkills(sourceDir, targetDir, {
+        force: options.force,
+        dryRun: options.dryRun
+      });
+      totalFiles += copiedFiles.length;
+      console.log(
+        `${
+          options.dryRun ? "Would copy" : "Copied"
+        } ${copiedFiles.length} file${copiedFiles.length === 1 ? "" : "s"}.`
+      );
+    } catch (error) {
+      console.error(`Failed to install skills for ${agent}: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
+
+  console.log(
+    `\nSummary: ${available.length} agent${
+      available.length === 1 ? "" : "s"
+    }, ${options.dryRun ? "would copy" : "copied"} ${totalFiles} file${
+      totalFiles === 1 ? "" : "s"
+    }.`
+  );
+}
+
+function registerInstallSkillsCommand(program) {
+  program
+    .command("install-skills")
+    .description("Install orrery skills for supported agents")
+    .option(
+      "--agent <agent>",
+      "Target agent (claude|codex|gemini|all); defaults to auto-detect"
+    )
+    .option("--force", "Overwrite existing skills")
+    .option("--dry-run", "Show what would be copied without writing files")
+    .action(installSkillsAction);
+}
+
+module.exports = registerInstallSkillsCommand;
+module.exports.installSkillsAction = installSkillsAction;

package/lib/cli/commands/orchestrate.js

@@ -0,0 +1,27 @@
+const { orchestrate } = require("../../orchestration");
+
+module.exports = function registerOrchestrateCommand(program) {
+  program
+    .command("orchestrate")
+    .alias("exec")
+    .description("Run plan orchestration for the current project")
+    .option("--plan <file>", "Process only a specific plan file")
+    .option("--dry-run", "Show what would be executed without running agents")
+    .option("--verbose", "Show detailed agent output")
+    .option("--resume", "Resume orchestration on the current work branch")
+    .option("--review", "Enable code review loop after each step")
+    .action(async (options) => {
+      try {
+        await orchestrate({
+          plan: options.plan,
+          dryRun: options.dryRun,
+          verbose: options.verbose,
+          resume: options.resume,
+          review: options.review
+        });
+      } catch (error) {
+        console.error(error && error.message ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+};