@caseyharalson/orrery 0.7.1

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

@@ -0,0 +1,119 @@
+---
+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.
+user-invocable: false
+---
+
+# Report Skill
+
+## When to Use
+
+Use this skill **after verification** to finalize your work on a step and communicate the result to the Orchestrator.
+
+**Triggers:**
+
+- Execution and Verification phases are complete.
+- You have been handed off from the **Verify** skill.
+- Or, you need to report a **Blocked** status.
+
+---
+
+## Output Contract (CRITICAL)
+
+The Orchestrator expects a **single JSON object** printed to `stdout`. This is how you "report" your status.
+
+**Success JSON:**
+
+```json
+{
+  "stepId": "<id>",
+  "status": "complete",
+  "summary": "Brief description of work done and verification results",
+  "artifacts": ["file1.js", "src/components/NewComp.tsx"],
+  "testResults": "Passed 8/8 tests",
+  "commitMessage": "feat: add user authentication with session handling"
+}
+```
+
+**Blocked JSON:**
+
+```json
+{
+  "stepId": "<id>",
+  "status": "blocked",
+  "blockedReason": "Detailed reason why the step cannot be completed",
+  "summary": "Work attempted but failed due to..."
+}
+```
+
+**Rules:**
+
+1. **NO Markdown:** Do not wrap the JSON in triple-backtick code blocks (e.g., ` ```json ... ``` `).
+2. **Clean Output:** Ensure the JSON is valid and on its own line.
+3. **One Object Per Step:** If you are working on multiple steps, you may output multiple JSON objects (one per line).
+
+---
+
+## How to Do It
+
+### Step 1: Gather Information
+
+Collect from your execution and verification:
+
+- **Status:** Did it pass verification? (`complete` vs `blocked`)
+- **Artifacts:** List of files created or modified.
+- **Summary:** A concise sentence describing the implementation.
+- **Test Results:** Summary of test outcomes (e.g., "Pass: 5, Fail: 0").
+
+### Step 2: Construct the JSON
+
+Map your gathered info to the JSON fields.
+
+- `stepId`: The ID from the plan you are working on.
+- `status`: "complete" (if verified) or "blocked".
+- `summary`: Human-readable explanation.
+- `artifacts`: Array of file paths.
+- `commitMessage`: A conventional commit message (e.g., "feat: add login", "fix: resolve null check").
+
+### Step 3: Output to Stdout
+
+Print the JSON string. **This is your final action.**
+
+---
+
+## Example
+
+**Scenario:** You implemented a "Login" feature (Step 3).
+
+**1. Handoff:** You came from `verify` where 2/2 tests passed.
+**2. Constructing Report:**
+
+- ID: "3"
+- Status: "complete"
+- Summary: "Implemented login logic."
+- Artifacts: ["src/auth/login.ts"]
+- Test Results: "2/2 passed"
+
+**3. Action:**
+
+```json
+{
+  "stepId": "3",
+  "status": "complete",
+  "summary": "Implemented login logic and verified with unit tests",
+  "artifacts": ["src/auth/login.ts"],
+  "testResults": "2/2 passed",
+  "commitMessage": "feat: add login endpoint with session handling"
+}
+```
+
+---
+
+## Common Pitfalls
+
+- **Outputting Text:** "I have finished the step." (The Orchestrator cannot read this).
+- **Markdown Blocks:** Wrapping JSON in ` ```json ... ``` ` breaks the parser.
+- **Invalid JSON:** Ensure the JSON is properly formatted and all strings are quoted.

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

@@ -0,0 +1,105 @@
+---
+name: orrery-review
+description: >
+  Review code changes after each step execution and provide structured feedback.
+user-invocable: false
+---
+
+# Review Skill
+
+## When to Use
+
+Use this skill **after a step execution** to review the changes and provide
+feedback to an editor agent.
+
+**Triggers:**
+
+- You are invoked by the orchestrator for a review phase.
+- You receive step context, list of modified files, and a git diff.
+
+**Do not** apply fixes yourself. Only review and report.
+
+---
+
+## How to Do It
+
+### Step 1: Read Context
+
+- Read the step description and requirements provided by the orchestrator.
+- Read the git diff to understand the changes.
+
+### Step 2: Read Full Files (Required)
+
+For every modified or added file, **read the full file contents** to
+understand broader context. Do not review only the diff.
+
+### Step 3: Review Criteria
+
+Check the changes against these criteria:
+
+- Correctness: Does the code do what it should? Any logic mistakes?
+- Bug risks: Edge cases, null handling, off-by-one errors.
+- Security: Injection, auth issues, data exposure, unsafe inputs.
+- Performance: Obvious inefficiencies, N+1 patterns, memory leaks.
+- Code quality: Readability, naming, complexity, maintainability.
+- Architecture: Duplication, separation of concerns, module boundaries.
+- Error handling: Errors handled gracefully, no silent failures.
+- Testing: Test coverage gaps, testability, missing edge cases.
+
+### Step 4: Prioritize Feedback
+
+- Mark **blocking** issues that must be fixed (bugs, security, correctness).
+- Mark **suggestions** for improvements that are optional or non-critical.
+- Keep feedback concise and actionable; avoid style-only nits.
+
+### Step 5: Decide Status
+
+- `approved` if there are **no blocking** issues.
+- `needs_changes` if **any blocking** issue exists.
+
+---
+
+## Output Contract (CRITICAL)
+
+Return a single JSON object to stdout.
+
+```json
+{
+  "status": "approved | needs_changes",
+  "feedback": [
+    {
+      "file": "path/to/file.js",
+      "line": 42,
+      "severity": "blocking | suggestion",
+      "comment": "Explain the issue and expected fix."
+    }
+  ]
+}
+```
+
+**Rules:**
+
+1. Output **valid JSON on a single line**.
+2. No markdown code blocks in your final output.
+3. `line` is optional if not applicable.
+4. `feedback` may be empty only when `status` is `approved`.
+
+---
+
+## Example
+
+**Scenario:** Missing null check in `src/service.js`.
+
+```json
+{
+  "status": "needs_changes",
+  "feedback": [
+    {
+      "file": "src/service.js",
+      "line": 87,
+      "severity": "blocking",
+      "comment": "Guard against null `user` before accessing `user.id` to avoid runtime errors."
+    }
+  ]
+}
+```

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

@@ -0,0 +1,105 @@
+---
+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.
+user-invocable: false
+---
+
+# Verify Skill
+
+## When to Use
+
+Use this skill **after execution** to validate that changes work correctly and meet acceptance criteria.
+
+**Triggers:**
+
+- Execution phase is complete.
+- You have been handed off from the **Execute** skill.
+
+**Never skip verification.** Even trivial changes should have at least basic checks.
+
+---
+
+## How to Do It
+
+### Step 0: Check Repository Guidelines
+
+Before running generic commands, check for project-specific instructions:
+
+1. **Plan metadata.notes** - Use testing/linting commands specified here
+2. **Project guideline files** - Check for files like `CLAUDE.md`, `AGENTS.md`, `COPILOT.md`, or similar at the repo root. Follow their validation steps (e.g., `npm run fix`, `npm run validate`)
+3. **CONTRIBUTING.md** - Check for any validation requirements
+
+Use project-specific commands instead of generic ones when available.
+
+### Step 1: Run the Test Suite
+
+Execute the project's tests:
+
+```bash
+# Common test commands
+npm test
+pytest
+go test ./...
+cargo test
+```
+
+### Step 2: Run Formatting and Linting
+
+If the project has formatting/linting configured:
+
+1. **Run formatters first** (e.g., `npm run fix`, `prettier --write`)
+2. **Then run linters** (e.g., `npm run lint`, `eslint .`)
+
+Check project guideline files and plan notes for the exact commands.
+
+### Step 2.5: Update CHANGELOG (if required)
+
+If project guideline files require CHANGELOG updates:
+
+1. Check if changes touch user-facing code (lib/, bin/, etc.)
+2. If yes, add an entry under `[Unreleased]` with appropriate category
+3. Use the correct category: Added, Changed, Fixed, Removed, Deprecated, Security
+
+### Step 3: Check Acceptance Criteria
+
+For each completed step, verify its `criteria` field from the plan.
+Ask yourself: Does the implementation actually satisfy this?
+
+### Step 4: Decision & Handoff
+
+**Case A: Verification FAILED**
+If tests fail, linting errors occur, or criteria are not met:
+
+1.  Analyze the error.
+2.  **Return to Execute:** Invoke the `orrery-execute` skill using the Skill tool to fix the issues.
+3.  _Do not_ proceed to Report until issues are resolved (unless completely blocked).
+
+**Case B: Verification PASSED**
+If all checks pass:
+
+1.  **Gather Stats:** Note the number of tests passed (e.g., "8/8 passed").
+2.  **Handoff to Report:** Invoke the `orrery-report` skill using the Skill tool to finalize the step.
+
+---
+
+## Example
+
+**Scenario:** You implemented `src/api/routes/upload.ts`.
+
+1.  **Run tests:** `npm test` -> **FAIL** (ReferenceError).
+    - **Action:** Invoke the `orrery-execute` skill using the Skill tool to fix the ReferenceError.
+
+2.  **Run tests (Attempt 2):** `npm test` -> **PASS** (5 tests passed).
+3.  **Run lint:** `npm run lint` -> **PASS**.
+4.  **Action:** Invoke the `orrery-report` skill using the Skill tool.
+
+---
+
+## Common Pitfalls
+
+- **Ignoring failures:** Passing a failed test suite to the Report skill.
+- **Skipping regression checks:** Not running the full suite to ensure old code still works.
+- **Infinite Loops:** If you keep bouncing between Execute and Verify without progress, stop and invoke the `orrery-report` skill using the Skill tool with a "Blocked" status.

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

@@ -0,0 +1,291 @@
+---
+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).
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "orrery validate-plan"
+---
+
+# Refine Plan Skill
+
+## When to Use
+
+Use this skill when you have an existing plan and want to **improve it** before execution. Unlike Simulate (which is read-only), Refine analyzes the plan and implements improvements directly.
+
+**Triggers:**
+
+- "This plan needs work"
+- "Can you improve this plan?"
+- "Check if this plan is ready for execution"
+- "The context seems thin, can you fill it out?"
+- "Make sure this plan follows the schema"
+- Plan validation failed and you need to fix issues
+
+**Skip if:**
+
+- No plan exists yet (use Discovery first)
+- You want to explore the plan interactively (use Simulate instead)
+- You need to fundamentally restructure the plan or change outcomes (use Discovery)
+- The plan is already validated and well-formed
+
+---
+
+## How to Do It
+
+### Step 1: Load and Parse the Plan
+
+Read the plan file and understand its structure:
+
+- Parse the YAML to identify all steps, dependencies, and metadata
+- Note the outcomes (what success looks like)
+- Map the dependency graph
+- Identify which steps have context_files, risk_notes, and other optional fields
+
+Announce what you've loaded:
+
+```
+I've loaded [plan name]. It has [N] steps with [X] outcomes.
+Let me analyze it for improvements.
+```
+
+### Step 2: Analyze for Improvements
+
+Check each improvement category systematically. Build a list of findings.
+
+For each issue found, note:
+
+- What the problem is
+- Which step(s) it affects
+- What the fix should be
+
+### Step 3: Report Findings or Exit Clean
+
+**If no improvements found:**
+
+```
+The plan looks good. No structural issues, dependencies are correct,
+context is sufficient for autonomous execution, and acceptance criteria
+are testable. Ready for execution.
+```
+
+Exit cleanly without modifying the file.
+
+**If improvements found:**
+
+```
+Found [N] improvements:
+- [Category]: [Brief description] (steps X, Y)
+- [Category]: [Brief description] (step Z)
+
+Implementing these changes now.
+```
+
+### Step 4: Implement Improvements
+
+Write the updated plan directly to the file. The PostToolUse hook will automatically validate the plan after writing.
+
+Make changes in order of impact:
+
+1. Schema compliance issues first (required fields)
+2. Structural issues (malformed steps)
+3. Dependency issues (missing deps, cycles)
+4. Context and criteria improvements
+
+### Step 5: Summarize Changes
+
+After writing:
+
+```
+Updated the plan with [N] changes:
+- Added missing deps to steps 2.1, 2.3 (they now depend on install step 0.1)
+- Expanded context for step 1.2 to include integration patterns
+- Made criteria in step 3.1 more specific and testable
+- Added risk_notes to step 2.1 (high complexity)
+
+Plan validated successfully.
+```
+
+---
+
+## Improvement Categories
+
+Check the plan against these categories:
+
+### Structural Issues
+
+- **Missing required fields**: Every step must have `id`, `description`, `context`, `requirements`, `criteria`
+- **Malformed step IDs**: IDs should follow `{feature}.{step}` format (e.g., "1.1", "2.3")
+- **Missing metadata**: Plan must have `created_at`, `created_by`, `outcomes`
+- **Empty arrays**: Requirements and criteria must have at least one item
+
+**Fix approach:** Add missing fields with sensible defaults or flag for user input if context is unclear.
+
+### Dependency Issues
+
+- **Missing install step deps**: If step "0.1" installs dependencies, ALL subsequent steps should include "0.1" in their deps
+- **Circular dependencies**: Step A depends on B, B depends on A
+- **Missing sequential deps**: Step uses output from another step but doesn't declare the dependency
+- **Unnecessary sequential deps**: Steps that could run in parallel but have artificial dependencies
+
+**Fix approach:** Add missing deps, remove circular deps, suggest parallelization opportunities.
+
+### Context Quality
+
+Thin context prevents autonomous execution. Check for:
+
+- **Vague context**: "Add the feature" without explaining what, where, or why
+- **Missing context_files**: Steps that reference existing code but don't list which files to read
+- **No integration guidance**: Steps that modify existing code without explaining the patterns to follow
+- **Assumed knowledge**: Context assumes the agent knows project-specific conventions
+
+**Fix approach:** Expand context with specifics. Add relevant context_files. Reference existing patterns.
+
+### Acceptance Criteria Quality
+
+Criteria must be **specific** and **testable**. Check for:
+
+- **Vague criteria**: "Works correctly" or "Handles errors"
+- **Untestable criteria**: "Code is clean" or "Performance is good"
+- **Missing criteria**: Steps with empty or single-item criteria arrays
+- **Inconsistent scope**: Criteria that don't match what the step actually delivers
+
+**Fix approach:** Rewrite vague criteria with specific, observable conditions. Add missing criteria based on requirements.
+
+**Examples:**
+
+- Bad: "Error handling works"
+- Good: "Returns 400 status with error message when input validation fails"
+
+- Bad: "Component renders correctly"
+- Good: "Component renders loading skeleton while data fetches; displays chart when data arrives; shows error message if API returns 500"
+
+### Risk Coverage
+
+- **High complexity without notes**: Steps with many requirements or external integrations but no risk_notes
+- **Missing edge cases**: Obvious failure modes not acknowledged
+- **Underestimated steps**: Steps that look simple but have hidden complexity
+
+**Fix approach:** Add risk_notes for complex steps. Call out edge cases and potential blockers.
+
+### Schema Compliance
+
+Validate against `../discovery/schemas/plan-schema.yaml`:
+
+- Field types match schema (arrays vs strings, required vs optional)
+- Status values are valid enum values
+- All referenced step IDs in deps actually exist
+
+**Fix approach:** Correct type mismatches, fix invalid values, remove dangling dep references.
+
+---
+
+## Reference Schema
+
+The plan schema is defined at:
+
+```
+agent/skills/discovery/schemas/plan-schema.yaml
+```
+
+Key required fields:
+
+- **metadata**: `created_at`, `created_by`, `outcomes`
+- **steps[].required**: `id`, `description`, `context`, `requirements`, `criteria`
+- **steps[].optional**: `status`, `deps`, `parallel`, `files`, `context_files`, `commands`, `risk_notes`
+
+---
+
+## Exit Conditions
+
+Exit **without changes** when:
+
+- All required fields are present
+- Dependencies are correct (no cycles, install steps properly referenced)
+- Context is sufficient for autonomous execution
+- Criteria are specific and testable
+- No schema violations
+
+In this case, report:
+
+```
+Plan analysis complete. No improvements needed.
+
+- Structure: Valid
+- Dependencies: Correct
+- Context: Sufficient
+- Criteria: Testable
+- Schema: Compliant
+
+Ready for execution.
+```
+
+---
+
+## Example Dialogue
+
+```
+User: /refine-plan .agent-work/plans/analytics-dashboard.yaml
+
+Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering
+two outcomes. Let me analyze it for improvements.
+
+Found 4 improvements:
+
+1. Dependency issues: Steps 1.1, 2.1, 2.2 don't depend on the install step (0.1)
+2. Context quality: Step 1.2 has thin context - doesn't explain the caching pattern
+3. Criteria quality: Step 2.3 has vague criteria ("error handling works")
+4. Risk coverage: Step 2.1 (Chart.js integration) has no risk_notes despite complexity
+
+Implementing these changes now.
+
+[Writes updated plan file]
+
+Updated the plan:
+- Added "0.1" to deps for steps 1.1, 2.1, 2.2
+- Expanded step 1.2 context with reference to cache.ts middleware pattern
+- Rewrote step 2.3 criteria: "Shows loading skeleton during fetch",
+  "Displays error toast with retry button on API failure"
+- Added risk_notes to step 2.1: "Chart.js bundle size impact - verify no
+  significant increase to main bundle"
+
+Plan validated successfully. Ready for execution.
+```
+
+---
+
+## Boundaries
+
+### What Refine Does
+
+- Fixes structural issues (missing fields, malformed data)
+- Corrects dependency problems
+- Expands thin context
+- Improves vague criteria
+- Adds missing risk notes
+- Ensures schema compliance
+
+### What Refine Does NOT Do
+
+- **Change outcomes**: If the outcomes are wrong, use Discovery
+- **Restructure the plan**: Refine improves existing steps, doesn't reorganize them
+- **Add new features**: Refine doesn't expand scope
+- **Remove steps**: Refine improves steps, doesn't delete them
+- **Question the approach**: That's what Simulate is for
+
+If you find yourself wanting to fundamentally change the plan (new steps, different outcomes, restructured features), suggest returning to Discovery instead.
+
+---
+
+## Common Pitfalls
+
+- **Over-refining**: Making changes that don't materially improve the plan. If it's good enough, say so.
+- **Changing scope**: Refine improves quality, not content. Don't add features or change what the plan delivers.
+- **Forgetting validation**: Always let the PostToolUse hook validate after writing. If validation fails, fix and write again.
+- **Missing the install step pattern**: This is the most common dependency issue. Always check if 0.1 exists and if subsequent steps depend on it.
+- **Vague improvements**: Don't just say "expanded context" - show specifically what changed.