@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/input-contract.schema.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "job-orchestrator-input-contract",
+  "title": "Job Orchestrator Input Contract",
+  "description": "Defines all input parameters required to run job-orchestrator. This is the top-level entry point for the AI implementation pipeline.",
+  "type": "object",
+  "required": ["issue", "codebase", "automation"],
+  "properties": {
+    "issue": {
+      "type": "object",
+      "description": "GitHub issue identification. Provide EITHER url OR repo+number.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Full GitHub issue URL",
+          "examples": ["https://github.com/<ORG>/<PROJECT>/issues/4141"]
+        },
+        "repo": {
+          "type": "string",
+          "pattern": "^[\\w.-]+/[\\w.-]+$",
+          "description": "GitHub owner/repo (alternative to url)",
+          "examples": ["<ORG>/<PROJECT>"]
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Issue number (alternative to url)",
+          "examples": [4141]
+        }
+      },
+      "oneOf": [
+        { "required": ["url"] },
+        { "required": ["repo", "number"] }
+      ]
+    },
+    "codebase": {
+      "type": "object",
+      "description": "Codebase configuration for implementation.",
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Absolute path to the repository root",
+          "examples": ["/Users/dev/<PROJECT>"]
+        },
+        "role": {
+          "type": "string",
+          "enum": ["frontend", "backend", "shared"],
+          "default": "frontend",
+          "description": "Role of this codebase"
+        },
+        "base_branch": {
+          "type": "string",
+          "default": "develop-2",
+          "description": "Base branch to create feature branch from"
+        },
+        "additional_codebases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "role"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "Absolute path"
+              },
+              "role": {
+                "type": "string",
+                "enum": ["frontend", "backend", "shared"]
+              },
+              "branch": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Additional codebases for issue-analyzer cross-repo analysis (read-only, implementation happens in primary codebase)"
+        }
+      }
+    },
+    "automation": {
+      "type": "object",
+      "description": "Controls for the orchestration pipeline.",
+      "required": ["skip_confirmation"],
+      "properties": {
+        "skip_confirmation": {
+          "type": "boolean",
+          "const": true,
+          "description": "Must be true — sub-agents run without confirmation"
+        },
+        "max_review_iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3,
+          "default": 2,
+          "description": "Max review → fix iterations"
+        },
+        "auto_create_pr": {
+          "type": "boolean",
+          "default": false,
+          "description": "Auto-create draft PR without asking user (default: ask)"
+        },
+        "reviewers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "code-ai-review",
+              "code-boss-review",
+              "code-style-review",
+              "code-mobx-store-review"
+            ]
+          },
+          "default": ["code-ai-review", "code-boss-review", "code-style-review"],
+          "description": "Review skills to always run"
+        },
+        "conditional_reviewers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {
+            "code-mobx-store-review": "*.store.ts"
+          },
+          "description": "Review skills to run conditionally: {skill_name: file_glob_pattern}"
+        },
+        "run_final_checks": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run lint/type-check/test after review loop"
+        },
+        "analyzer_settings": {
+          "type": "object",
+          "description": "Settings passed to issue-analyzer sub-agent",
+          "properties": {
+            "max_tasks": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "default": 7
+            },
+            "search_depth": {
+              "type": "string",
+              "enum": ["shallow", "focused", "deep"],
+              "default": "focused"
+            },
+            "include_context": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
+        "implementer_settings": {
+          "type": "object",
+          "description": "Settings passed to task-implementer sub-agents",
+          "properties": {
+            "auto_commit": {
+              "type": "boolean",
+              "default": true
+            },
+            "verify_lint": {
+              "type": "boolean",
+              "default": true
+            },
+            "verify_types": {
+              "type": "boolean",
+              "default": true
+            },
+            "verify_tests": {
+              "type": "boolean",
+              "default": true
+            },
+            "verify_stories": {
+              "type": "boolean",
+              "default": false
+            },
+            "max_self_fix_attempts": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 5,
+              "default": 3
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/orchestrator-prompt.md

@@ -0,0 +1,179 @@
+# Job Orchestrator — Quick Reference Checklist
+
+> **Purpose:** Condensed execution checklist for the orchestrator agent.
+> This file is a quick reference — the full specification is in `SKILL.md`.
+> The orchestrator is NOT a sub-agent; it IS the primary agent executing this checklist.
+> When in doubt, refer to `SKILL.md` for complete details.
+
+## Data Flow
+
+```
+[User] → "implement issue #4141" / "analyze issue" / other request
+     ↓
+[Orchestrator] → loads SKILL.md, follows this checklist
+     ↓
+Phase 0: Context collection, intent determination, plan building
+     ↓
+Phase 1: [job-documenter sub-agent] → initialize .metaproject/jobs/<job-name>/ + README + plan
+     ↓
+Phase 2: Execute plan dynamically:
+     ↓
+     ├─ [issue-analyzer sub-agent] → JSON analysis result
+     ├─ git worktree add → feature branch (NEVER git checkout -b)
+     ├─ FOR EACH wave → [wave-executor sub-agent] → compact WAVE_DONE summary
+     ├─ Load review skills → findings
+     ├─ IF findings → [task-implementer sub-agent (fix)] → re-review (max 2x)
+     ├─ npm run lint && type-check && test
+     └─ [job-documenter] → document each step result
+     ↓
+Phase 3: [job-documenter] → finalize → final report
+     ↓
+(Optional) gh pr create --draft
+```
+
+## Phase 0: Context Collection (Guard Clause)
+
+Before starting, determine intent and collect context:
+
+1. **Determine intent** from user request:
+   - "Implement issue" → `implement` (full cycle)
+   - "Analyze issue" / "Study issue" → `analyze` (analysis first, then offer implementation)
+   - "Review" → `review` (review only)
+   - Other → `custom` (dynamic plan)
+
+2. **Project directory** → ALWAYS ask, never assume:
+   ```
+   Which project directory should I use?
+   ○ Type the full absolute path to your project
+   ```
+
+3. **Base branch** → ask to confirm (no default).
+
+4. **Job name** → auto-generate + confirm:
+   - `issue-<N>--<slug>` for implement
+   - `analysis--issue-<N>` for analyze
+   - `review--<slug>` for review
+   - `task--<slug>` for custom
+
+5. **Additional questions** by intent:
+   - `implement`: Create PR? (default: yes)
+   - `analyze`: nothing (ask about implementation after analysis)
+
+6. **Show summary and ask for confirmation** before starting.
+
+## Phase 1: Initialize Documentation
+
+Dispatch `job-documenter` sub-agent with `ACTION: init`.
+
+Write initial `state.json` to `.metaproject/jobs/<job-name>/state.json` after job docs are initialized.
+
+Verify `DOCUMENTER_RESULT.status == "success"`.
+
+## Phase 2: Execute Plan
+
+Execute plan steps sequentially. After each step:
+1. Collect result
+2. Send to `job-documenter` (ACTION: add-document)
+3. Update README (ACTION: update-readme)
+4. Update `state.json` with step completion
+5. Mark step as completed
+
+### Step: ANALYZE
+
+Read `skills/issue-analyzer/orchestrator-prompt.md`, fill in parameters:
+
+```
+ISSUE_URL: <url>   (or ISSUE_REPO + ISSUE_NUMBER)
+CODEBASE_PATHS: [{path, role, branch}]
+MAX_TASKS: 7 (default)
+SEARCH_DEPTH: focused (default)
+```
+
+Launch Task(issue-analyzer). Parse JSON result — extract tasks and dependency_order.
+
+For `analyze` intent: show result, ask "Implement? (yes/no)".
+- yes → extend plan: prepare → implement → review → fix → checks → report → pr
+- no → Phase 3
+
+### Step: PREPARE — Create Feature Branch
+
+> **CRITICAL**: Use ONLY `git worktree add`. NEVER `git checkout -b`.
+
+```bash
+git -C <project_dir> fetch origin <base_branch>
+git -C <project_dir> worktree add ../<branch-slug> -b feature/<branch-slug> origin/<base_branch>
+npm install --prefix <worktree_path>
+```
+
+All subsequent operations ONLY in worktree directory.
+
+### Step: IMPLEMENT — Wave Isolation
+
+```
+WAVES = topological_sort_into_waves(dependency_order, task_dependencies)
+
+FOR wave_index, wave_tasks in enumerate(WAVES):
+  1. Dispatch single Agent("wave-executor") with all tasks in this wave
+     (see skills/job-orchestrator/SKILL.md step 2.4.1 for full prompt template)
+  2. Receive compact WAVE_RESULT:
+       STATUS: WAVE_DONE | WAVE_PARTIAL | WAVE_FAILED
+       Commits: [hash msg, ...]
+       Tests: N passed, M failed
+       Tasks: task-1 ✅, task-2 ✅
+  3. Decision:
+       WAVE_DONE    → continue to next wave
+       WAVE_PARTIAL → log concerns (read result files if needed), continue
+       WAVE_FAILED  → STOP, read result files for failed tasks, ask user
+
+Do NOT dispatch task-implementers directly — always via wave-executor.
+Context budget rule: orchestrator only accumulates compact wave summaries,
+never raw task-implementer output.
+```
+
+Document result in job-documenter.
+
+### Step: REVIEW — Run Reviewers
+
+```
+REVIEWERS = ["code-ai-review", "code-boss-review", "code-style-review"]
+IF *.store.ts modified: add "code-mobx-store-review"
+
+FOR reviewer in REVIEWERS:
+  Load skill → execute → collect findings as JSON
+```
+
+Document result.
+
+### Step: FIX — Review-Fix Loop (max 2 iterations)
+
+If CRITICAL or WARNING findings exist:
+1. Group by file
+2. Launch task-implementer (task_type: "fix") with review findings JSON
+3. Re-run reviewers
+4. Recount findings
+
+### Step: CHECKS — Final Verification
+
+```bash
+npm run lint
+npm run type-check
+npm test
+```
+
+### Step: REPORT — Generate Final Report
+
+Markdown report per template in SKILL.md (section 2.9).
+
+### Step: PR — Propose Draft PR (optional)
+
+Dispatch `pr-issue-documenter` to generate PR description.
+Present to user, ask confirmation, then:
+```bash
+gh pr create --title "<title>" --body "..." --base <base> --head <head> --draft
+```
+
+## Phase 3: Completion
+
+1. Dispatch `job-documenter` with `ACTION: finalize`
+2. Update `state.json` with `phase: "COMPLETION"`
+3. Tell user what was accomplished + documentation path + PR URL (if created)

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/output-contract.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "job-orchestrator-output-contract",
+  "title": "Job Orchestrator Output Contract",
+  "description": "Defines the structure of the final report and PR proposal produced by job-orchestrator.",
+  "type": "object",
+  "required": ["format", "structure"],
+  "properties": {
+    "format": {
+      "type": "string",
+      "const": "markdown",
+      "description": "Output is in Markdown format (not Gherkin — this is the top-level human-readable report)"
+    },
+    "structure": {
+      "type": "object",
+      "description": "Structure of the implementation report",
+      "required": ["sections"],
+      "properties": {
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Summary",
+              "Tasks",
+              "Review Results",
+              "Unresolved Issues",
+              "Final Checks",
+              "Changes Summary",
+              "PR Proposal"
+            ]
+          },
+          "description": "Sections in the report"
+        }
+      }
+    },
+    "report_fields": {
+      "type": "object",
+      "description": "Key fields in the report for programmatic access",
+      "properties": {
+        "summary": {
+          "type": "object",
+          "properties": {
+            "issue_number": { "type": "integer" },
+            "issue_title": { "type": "string" },
+            "issue_type": { "type": "string" },
+            "branch_name": { "type": "string" },
+            "tasks_completed": { "type": "integer" },
+            "tasks_total": { "type": "integer" },
+            "review_iterations": { "type": "integer" },
+            "final_status": {
+              "type": "string",
+              "enum": ["READY FOR PR", "HAS WARNINGS", "HAS ISSUES", "FAILED"]
+            }
+          }
+        },
+        "task_results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "task_id": { "type": "string" },
+              "task_name": { "type": "string" },
+              "status": { "type": "string", "enum": ["success", "partial", "failed"] },
+              "files": { "type": "array", "items": { "type": "string" } },
+              "commits": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "review_results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "reviewer": { "type": "string" },
+              "critical": { "type": "integer" },
+              "warning": { "type": "integer" },
+              "info": { "type": "integer" }
+            }
+          }
+        },
+        "final_checks": {
+          "type": "object",
+          "properties": {
+            "lint": { "type": "string" },
+            "type_check": { "type": "string" },
+            "tests": { "type": "string" }
+          }
+        },
+        "pr_data": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string" },
+            "base": { "type": "string" },
+            "head": { "type": "string" },
+            "draft": { "type": "boolean" },
+            "body": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/state.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://keryx.local/schemas/job-orchestrator/state.schema.json",
+  "title": "Job Orchestrator State",
+  "description": "Schema for .metaproject/jobs/<job-name>/state.json — persisted orchestrator state for job resumption.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["phase", "intent", "job_name", "context", "plan"],
+  "properties": {
+    "phase": {
+      "type": "string",
+      "enum": ["CONTEXT", "PLAN", "EXECUTION", "COMPLETION"],
+      "description": "Current orchestrator phase"
+    },
+    "intent": {
+      "type": "string",
+      "enum": ["implement", "analyze", "review", "custom"]
+    },
+    "create_pr": { "type": "boolean" },
+    "job_name": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "context": {
+      "type": "object",
+      "properties": {
+        "issue": {
+          "type": "object",
+          "properties": {
+            "number": { "type": "integer" },
+            "title": { "type": "string" },
+            "url": { "type": "string" },
+            "type": { "type": "string" }
+          }
+        },
+        "project_dir": { "type": "string" },
+        "base_branch": { "type": "string" }
+      }
+    },
+    "branch": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "worktree_path": { "type": "string" },
+        "merge_base": { "type": "string" },
+        "package_manager": { "type": "string", "enum": ["npm", "bun", "yarn", "pnpm", "python", "go", "unknown"] },
+        "run_command": { "type": "string", "description": "Command prefix for running scripts (e.g., 'npm run', 'bun run', 'yarn')" }
+      }
+    },
+    "interview": {
+      "type": "object",
+      "description": "Results from the interview skill (Phase 0.3)",
+      "properties": {
+        "decisions": { "type": "array", "items": { "type": "object" } },
+        "constraints": { "type": "array", "items": { "type": "string" } },
+        "assumptions": { "type": "array", "items": { "type": "string" } },
+        "risks": { "type": "array", "items": { "type": "string" } },
+        "refined_goal": { "type": "string" }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "required": ["steps"],
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "type", "agent", "status"],
+            "properties": {
+              "id": { "type": "string" },
+              "type": { "type": "string" },
+              "agent": { "type": "string" },
+              "depends": { "type": "array", "items": { "type": "string" } },
+              "status": {
+                "type": "string",
+                "enum": ["pending", "in_progress", "completed", "skipped", "failed"]
+              },
+              "conditional": { "type": "boolean" }
+            }
+          }
+        },
+        "current_step": { "type": "string" }
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "properties": {
+        "total_tasks": { "type": "integer" },
+        "tasks": { "type": "array" },
+        "dependency_order": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "context_doc": {
+      "type": "object",
+      "properties": {
+        "path": { "type": "string" },
+        "version": { "type": "string" },
+        "status": { "type": "string", "enum": ["collected", "updated", "not-collected"] }
+      }
+    },
+    "implementation": {
+      "type": "object",
+      "properties": {
+        "task_results": { "type": "object" },
+        "all_commits": { "type": "array", "items": { "type": "string" } },
+        "all_files": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "review": {
+      "type": "object",
+      "properties": {
+        "iteration": { "type": "integer" },
+        "findings": { "type": "array" },
+        "needs_fix": { "type": "boolean" },
+        "unresolved": { "type": "array" }
+      }
+    },
+    "final_checks": {
+      "type": "object",
+      "properties": {
+        "lint": { "type": "string" },
+        "type_check": { "type": "string" },
+        "tests": { "type": "string" }
+      }
+    },
+    "documentation": {
+      "type": "object",
+      "properties": {
+        "job_path": { "type": "string" },
+        "documents_created": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "description": "Timing and token usage per step",
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "step_id": { "type": "string" },
+              "started_at": { "type": "string", "format": "date-time" },
+              "completed_at": { "type": "string", "format": "date-time" },
+              "duration_ms": { "type": "integer" },
+              "total_tokens": { "type": "integer" },
+              "status": { "type": "string" },
+              "retries": { "type": "integer" }
+            }
+          }
+        },
+        "total_duration_ms": { "type": "integer" },
+        "total_tokens": { "type": "integer" }
+      }
+    },
+    "jobs_root": {
+      "type": "string",
+      "description": "Resolved jobs root directory"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC timestamp of last state update"
+    }
+  }
+}