@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/output-contract.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://keryx.local/schemas/issue-analyzer/output-contract.schema.json",
+  "title": "Issue Analyzer Output Contract",
+  "description": "JSON output from issue-analyzer. Replaces the previous Gherkin format for reliable machine parsing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["issue", "tasks", "dependency_order"],
+  "properties": {
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["number", "title", "type", "repo", "intent", "total_tasks"],
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "title": { "type": "string" },
+        "type": { "type": "string", "enum": ["bug", "feature", "enhancement", "refactoring", "chore"] },
+        "repo": { "type": "string", "description": "owner/repo format" },
+        "intent": { "type": "string", "description": "1-2 sentence intent summary" },
+        "labels": { "type": "array", "items": { "type": "string" } },
+        "assignees": { "type": "array", "items": { "type": "string" } },
+        "total_tasks": { "type": "integer", "minimum": 1, "maximum": 10 }
+      }
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 10,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["task_id", "task_name", "task_type", "complexity", "dependencies", "description", "target_files", "acceptance_criteria"],
+        "properties": {
+          "task_id": { "type": "string", "pattern": "^task-[0-9]+$" },
+          "task_name": { "type": "string", "minLength": 1 },
+          "task_type": {
+            "type": "string",
+            "enum": ["ui_component", "store_logic", "service_api", "refactoring", "fix", "mixed"]
+          },
+          "complexity": { "type": "string", "enum": ["low", "medium", "high"] },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^task-[0-9]+$" }
+          },
+          "description": { "type": "string", "minLength": 1 },
+          "target_files": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "acceptance_criteria": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "context": { "type": "string" },
+          "existing_tests": { "type": "array", "items": { "type": "string" } },
+          "existing_stories": { "type": "array", "items": { "type": "string" } },
+          "module_patterns": { "type": "string" }
+        }
+      }
+    },
+    "dependency_order": {
+      "type": "array",
+      "description": "Topologically sorted task IDs — safe execution order",
+      "items": { "type": "string", "pattern": "^task-[0-9]+$" }
+    }
+  }
+}

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.codex.md

@@ -0,0 +1,365 @@
+---
+name: job-documenter
+description: "Creates and maintains structured job documentation in jobs/. Called by job-orchestrator to initialize job folders, create analysis/report/review documents, and maintain the job README. Follows jobs-documentation.mdc conventions."
+triggers:
+  - "Document job"
+  - "Initialize job folder"
+  - "Save job report"
+  - "Add job document"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "documentation"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+# Job Documenter
+
+## Purpose
+
+Sub-agent responsible for creating and maintaining structured job documentation in `.metaproject/jobs/`. Called exclusively by `job-orchestrator` to persist the lifecycle of orchestrated tasks — from initial plan through analysis, implementation, review, and final report.
+
+**This skill is NOT invoked directly by users.** It is a service skill dispatched by the orchestrator.
+
+**Input:** Action type + job name + content payload (from orchestrator)
+**Output:** Status report (success/error) + created file paths
+
+## When to Use
+
+- Called by `job-orchestrator` during pipeline execution
+- When orchestrator needs to initialize a new job folder
+- When orchestrator needs to save a sub-agent result as a document
+- When orchestrator needs to update job README or finalize a job
+
+## Reference Rule
+
+All structural conventions are defined in `rules/core/jobs-documentation.mdc`. This skill MUST follow that rule exactly.
+
+## Input Contract
+
+The orchestrator provides a structured prompt with the following fields:
+
+```
+ACTION:    init | add-document | update-readme | finalize
+JOB_NAME:  <kebab-case folder name>
+JOBS_ROOT: .metaproject/jobs
+DATA:      <action-specific payload — see below>
+```
+
+---
+
+## Actions
+
+### Action: `init`
+
+Initialize a new job folder with required structure.
+
+**Input DATA:**
+```
+TITLE:       <Job title — human-readable>
+DESCRIPTION: <1-3 sentences describing what this job does>
+INTENT:      <analyze | implement | review | custom>
+SOURCE:      <issue URL, PR URL, branch name, or free-text description>
+PROJECT:     <absolute path to project directory>
+BRANCH:      <feature branch name, if known — may be "TBD">
+BASE_BRANCH: <base branch name>
+PLAN:        <ordered list of planned steps>
+```
+
+**Procedure:**
+
+1. **Create directory structure:**
+   ```
+   .metaproject/jobs/<JOB_NAME>/
+     README.md
+     man/
+     ai/
+   ```
+
+2. **Write README.md** following the format from `jobs-documentation.mdc`:
+   - Status: `in-progress`
+   - Created/Updated: current ISO 8601 UTC timestamp
+   - Fill Context table from input DATA
+   - Plan section from input PLAN (all items unchecked)
+   - Empty Agents Used table
+   - Empty Documents tables
+   - Empty Problems & Notes
+
+3. **Write `ai/plan.md`** — structured version of the plan:
+   ```markdown
+   # Execution Plan
+
+   ## Steps
+   | Step | Type | Agent | Dependencies | Status |
+   |------|------|-------|-------------|--------|
+   | 1 | analyze | issue-analyzer | none | pending |
+   | 2 | prepare | orchestrator | 1 | pending |
+   | ... | ... | ... | ... | ... |
+
+   ---
+
+   <!-- Document Metadata -->
+   | Key | Value |
+   |-----|-------|
+   | Created | <timestamp> |
+   | Agent | job-orchestrator |
+   | Task | Initialize job plan |
+   | Job | <JOB_NAME> |
+   | Version | 1.0 |
+   | Status | final |
+   ```
+
+4. **Write `man/plan.md`** — human-readable version of the plan:
+   ```markdown
+   # Execution Plan: <TITLE>
+
+   ## Overview
+   <DESCRIPTION>
+
+   ## Steps
+
+   1. **<Step name>** — <description>
+      - Agent: <agent name>
+      - Dependencies: <deps or "none">
+
+   2. ...
+
+   ---
+
+   <!-- Document Metadata -->
+   | Key | Value |
+   |-----|-------|
+   | Created | <timestamp> |
+   | Agent | job-orchestrator |
+   | Task | Initialize job plan |
+   | Job | <JOB_NAME> |
+   | Version | 1.0 |
+   | Status | final |
+   ```
+
+5. **Update README.md** — add plan.md entries to Documents tables.
+
+6. **Verify:**
+   - Read directory listing of `.metaproject/jobs/<JOB_NAME>/`
+   - Confirm: `README.md`, `man/`, `ai/`, `man/plan.md`, `ai/plan.md` all exist
+   - If any missing → report error
+
+7. **Return result:**
+   ```
+   DOCUMENTER_RESULT:
+     action: init
+     status: success | error
+     job_path: .metaproject/jobs/<JOB_NAME>
+     files_created: [README.md, man/plan.md, ai/plan.md]
+     error_details: <if status is error>
+   ```
+
+---
+
+### Action: `add-document`
+
+Add a new document to an existing job.
+
+**Input DATA:**
+```
+DOC_TYPE:    <analysis | report | review | context | implementation-report | final-report | improvements | requirements | error-log | tasks.feature | review-findings | custom>
+DOC_NAME:    <file name without extension, kebab-case — used if DOC_TYPE is "custom">
+TARGET:      man | ai | both
+TITLE:       <document title>
+CONTENT:     <full document content — markdown>
+AGENT:       <which agent produced this content>
+TASK:        <which task/phase this relates to>
+VERSION:     <document version, default "1.0">
+DOC_STATUS:  <draft | final>
+```
+
+**Procedure:**
+
+1. **Determine file name:**
+   - If DOC_TYPE is a standard type → use standard name from `jobs-documentation.mdc` (e.g. `analysis.md`, `report.md`)
+   - If DOC_TYPE is `tasks.feature` → use `tasks.feature` (ai/ only)
+   - If DOC_TYPE is `custom` → use DOC_NAME + `.md`
+
+2. **Determine target directories:**
+   - `TARGET=man` → write to `man/` only
+   - `TARGET=ai` → write to `ai/` only
+   - `TARGET=both` → write to both `man/` and `ai/`
+
+3. **For each target directory, write the document:**
+   ```markdown
+   # <TITLE>
+
+   <CONTENT>
+
+   ---
+
+   <!-- Document Metadata -->
+   | Key | Value |
+   |-----|-------|
+   | Created | <current ISO 8601 UTC timestamp> |
+   | Agent | <AGENT> |
+   | Task | <TASK> |
+   | Job | <JOB_NAME> |
+   | Version | <VERSION> |
+   | Status | <DOC_STATUS> |
+   ```
+
+4. **Update README.md:**
+   - Add entry to the appropriate Documents table(s) (`man/` and/or `ai/`)
+   - Entry format: `| [<filename>](<target>/<filename>) | <TITLE> | <DOC_STATUS> |`
+
+5. **Verify:**
+   - Confirm each written file exists by reading directory listing
+   - Confirm README.md was updated (contains the new file reference)
+
+6. **Return result:**
+   ```
+   DOCUMENTER_RESULT:
+     action: add-document
+     status: success | error
+     files_created: [<list of created file paths>]
+     readme_updated: true | false
+     error_details: <if status is error>
+   ```
+
+---
+
+### Action: `update-readme`
+
+Refresh the README to reflect current state.
+
+**Input DATA:**
+```
+PLAN_UPDATES:  <optional — list of step statuses to update: [{step: 1, status: "completed"}, ...]>
+AGENTS_UPDATE: <optional — list of agent entries to add/update: [{agent, phase, status}, ...]>
+PROBLEMS:      <optional — list of problems/notes to add>
+BRANCH_UPDATE: <optional — branch name if it was TBD during init>
+```
+
+**Procedure:**
+
+1. **Read current README.md** from `.metaproject/jobs/<JOB_NAME>/README.md`
+
+2. **Apply updates:**
+   - Update plan checkboxes based on PLAN_UPDATES (`[ ]` → `[x]` for completed steps)
+   - Add/update rows in Agents Used table
+   - Append to Problems & Notes section
+   - Update Branch in Context table if BRANCH_UPDATE provided
+   - Update `**Updated:**` timestamp
+
+3. **Re-scan `man/` and `ai/` directories** to ensure Documents tables are complete:
+   - List all files in `man/` and `ai/`
+   - If any file exists that is NOT in the Documents table → add it with description "Auto-discovered"
+   - If any table entry references a file that doesn't exist → mark as "(missing)"
+
+4. **Write updated README.md**
+
+5. **Return result:**
+   ```
+   DOCUMENTER_RESULT:
+     action: update-readme
+     status: success | error
+     updates_applied: [<list of what was updated>]
+     error_details: <if status is error>
+   ```
+
+---
+
+### Action: `finalize`
+
+Mark the job as completed.
+
+**Input DATA:**
+```
+FINAL_CONTENT: <optional — final report content to save as final-report.md>
+FINAL_STATUS:  completed | aborted
+SUMMARY:       <1-3 sentence summary of what was accomplished>
+```
+
+**Procedure:**
+
+1. **If FINAL_CONTENT is provided:**
+   - Write `man/final-report.md` and `ai/final-report.md` with metadata (same as `add-document` procedure)
+   - Update README Documents tables
+
+2. **Update README.md:**
+   - Set Status to FINAL_STATUS
+   - Update `**Updated:**` timestamp
+   - Mark all plan steps as completed (or appropriate status)
+   - Add SUMMARY to Description section (or as a "## Outcome" section at the end)
+
+3. **Full verification:**
+   - Read directory listing of `.metaproject/jobs/<JOB_NAME>/`, `man/`, `ai/`
+   - Cross-check every entry in README Documents tables against actual files
+   - Report any discrepancies
+
+4. **Return result:**
+   ```
+   DOCUMENTER_RESULT:
+     action: finalize
+     status: success | error
+     job_path: .metaproject/jobs/<JOB_NAME>
+     final_status: <FINAL_STATUS>
+     total_documents: <count of all files in man/ + ai/>
+     verification: passed | <list of discrepancies>
+     error_details: <if status is error>
+   ```
+
+---
+
+## Error Handling
+
+If any file operation fails during any action:
+
+1. **Attempt to create error log:**
+   - Write `man/error-log.md` with error details, timestamp, which action was being performed
+   - If this also fails, report the raw error in the return result
+
+2. **Return error status:**
+   ```
+   DOCUMENTER_RESULT:
+     action: <action>
+     status: error
+     error_details: <what went wrong>
+     error_log_created: true | false
+   ```
+
+3. **Do NOT throw/crash** — always return a structured result so the orchestrator can decide how to proceed.
+
+---
+
+## Prompt Template for Orchestrator
+
+When the orchestrator dispatches this skill as a sub-agent, it should use this prompt structure:
+
+```
+You are the job-documenter agent. Your task is to manage job documentation.
+
+Load the skill from: skills/job-documenter/SKILL.md
+Follow the rules from: rules/core/jobs-documentation.mdc
+
+ACTION: <action>
+JOB_NAME: <job-name>
+JOBS_ROOT: .metaproject/jobs
+
+DATA:
+<action-specific data>
+
+Execute the action and return a DOCUMENTER_RESULT block.
+```
+
+---
+
+## Rules of Engagement
+
+1. **DO** follow `jobs-documentation.mdc` for all structural decisions.
+2. **DO** add metadata blocks to every document.
+3. **DO** verify file existence after every write operation.
+4. **DO** keep README.md in sync with actual directory contents.
+5. **DO** use ISO 8601 UTC timestamps everywhere.
+6. **DO** return structured DOCUMENTER_RESULT for every action.
+7. **DO NOT** create files outside of `.metaproject/jobs/<JOB_NAME>/`.
+8. **DO NOT** delete or overwrite existing documents without explicit instruction.
+9. **DO NOT** modify files in other job folders.
+10. **DO NOT** interact with the user directly — all communication goes through the orchestrator.