@caseyharalson/orrery 0.14.4 → 0.15.1

package/HELP.md

@@ -266,8 +266,9 @@ 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).
+agent applies fixes and verification re-runs, repeating until approval. If the
+max iteration limit is reached without approval, the step is blocked (default:
+3).
 
 ### Background Execution
 

package/agent/skills/discovery/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: discovery
 description: >
-  Create executable plans for building systems, features, or modules. Use for
-  planning requests, architectural decisions, or when decomposing big ideas
-  into concrete implementation steps.
+  Author an orrery plan — a YAML file under the orrery plans directory that
+  the orrery CLI executes step-by-step. Use ONLY when the user explicitly
+  asks to create an orrery plan (e.g., "make an orrery plan", "use orrery
+  discovery", "/discovery"). Do NOT use for general planning, architectural
+  discussion, or decomposing ideas unless the output is an orrery plan file.
 hooks:
   PostToolUse:
     - matcher: "Write"

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

@@ -1,7 +1,10 @@
 ---
 name: orrery-execute
 description: >
-  Write or modify code according to a plan step. Handle implementation.
+  Implement a single step from an orrery plan (YAML file under the orrery
+  plans directory) when invoked by the orrery orchestrator. Do NOT use for
+  general coding, bug fixes, or implementation work outside of an orrery
+  plan run.
 user-invocable: false
 ---
 

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

@@ -1,9 +1,11 @@
 ---
 name: orrery-report
 description: >
-  Final reporting phase for the orrery workflow. Outputs structured JSON
-  summarizing execution results, test outcomes, and status. Use after
-  orrery-verify completes or when reporting blocked status.
+  Final reporting phase for a single step of an orrery plan, invoked by the
+  orrery orchestrator after orrery-verify completes (or when reporting blocked
+  status). Outputs structured JSON consumed by the orrery orchestrator. Do
+  NOT use for general status summaries or reports outside of an orrery plan
+  run.
 user-invocable: false
 ---
 

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

@@ -1,7 +1,10 @@
 ---
 name: orrery-review
 description: >
-  Review code changes after each step execution and provide structured feedback.
+  Review changes made for a single step of an orrery plan (YAML file under
+  the orrery plans directory) when invoked by the orrery orchestrator, and
+  produce structured feedback for the editor agent. Do NOT use for general
+  code review outside of an orrery plan run.
 user-invocable: false
 ---
 

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

@@ -1,9 +1,11 @@
 ---
 name: orrery-verify
 description: >
-  Run tests, linting, and validation to verify changes work correctly.
-  Use after implementation to check acceptance criteria, run test suites,
-  and ensure nothing is broken.
+  Verify a single step from an orrery plan (YAML file under the orrery plans
+  directory) when invoked by the orrery orchestrator after orrery-execute.
+  Runs the plan step's acceptance criteria, tests, and linting. Do NOT use
+  for general test runs, linting, or verification work outside of an orrery
+  plan run.
 user-invocable: false
 ---
 

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

@@ -1,10 +1,12 @@
 ---
 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 my-plan.yaml).
-  Run `orrery plans-dir` to find the plans directory.
+  Analyze and improve an existing orrery plan (YAML file under the orrery
+  plans directory). Reviews plan structure, dependencies, context quality,
+  and acceptance criteria, then edits the plan file directly. Use ONLY when
+  the user explicitly asks to refine an orrery plan and provides a plan file
+  argument (e.g., /refine-plan my-plan.yaml). Run `orrery plans-dir` to find
+  the plans directory. Do NOT use for general plan or design-doc review.
 hooks:
   PostToolUse:
     - matcher: "Write"

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

@@ -1,10 +1,12 @@
 ---
 name: simulate-plan
 description: >
-  Explore a plan through conversational dialogue before committing to execution.
-  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.
+  Explore an existing orrery plan (YAML file under the orrery plans directory)
+  through conversational dialogue before committing to execution. Use ONLY
+  when the user explicitly asks to simulate an orrery plan and provides a
+  plan file argument (e.g., /simulate-plan my-plan.yaml, /simulate-plan
+  my-plan). Run `orrery plans-dir` to find the plans directory. Do NOT use
+  for general "what if" brainstorming outside of an orrery plan.
 ---
 
 # Simulate Skill

package/lib/orchestration/index.js

@@ -80,6 +80,8 @@ const { acquireLock, releaseLock } = require("../utils/lock");
 const { isStopRequested, clearStopSignal } = require("../utils/stop-signal");
 
 const REPO_ROOT = process.cwd();
+const REVIEW_MAX_ITERATIONS_BLOCKED_REASON =
+  "Review max iterations reached without approval.";
 
 function parseArgs(argv) {
   const options = {
@@ -210,6 +212,17 @@ function resolvePlanFile(planArg, plansDir) {
   return null;
 }
 
+function blockStepAfterReviewMaxIterations(stepResult) {
+  return {
+    ...stepResult,
+    status: "blocked",
+    summary:
+      stepResult.summary ||
+      "Step blocked because review did not approve the changes.",
+    blockedReason: REVIEW_MAX_ITERATIONS_BLOCKED_REASON
+  };
+}
+
 function logDryRunSummary(planFiles) {
   console.log("Dry run: no changes will be made.");
   if (planFiles.length === 0) {
@@ -1762,8 +1775,9 @@ async function waitForAgentCompletion(
 
         if (!approved && currentResult.status === "complete") {
           console.log(
-            `[WARN] Review max iterations reached for step ${stepId}. Proceeding without approval.`
+            `[WARN] Review max iterations reached for step ${stepId}. Blocking step without approval.`
           );
+          currentResult = blockStepAfterReviewMaxIterations(currentResult);
         }
 
         stepResult = currentResult;
@@ -2033,4 +2047,9 @@ if (require.main === module) {
   });
 }
 
-module.exports = { orchestrate, runOnCompleteHook };
+module.exports = {
+  orchestrate,
+  runOnCompleteHook,
+  blockStepAfterReviewMaxIterations,
+  REVIEW_MAX_ITERATIONS_BLOCKED_REASON
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caseyharalson/orrery",
-  "version": "0.14.4",
+  "version": "0.15.1",
   "description": "Workflow planning and orchestration CLI for AI agents",
   "license": "MIT",
   "author": "Casey Haralson",