octocode-cli 1.2.5 → 1.2.7

package/skills/octocode-documentation-writer/schemas/qa-results-schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/qa-results.json",
+  "title": "QA Validator Results",
+  "description": "Final quality assurance report from Phase 6",
+  "type": "object",
+  "required": ["metadata", "overall_score", "quality_rating", "ready_for_use", "score_breakdown", "question_coverage", "gaps"],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": ["version", "generated_at", "repository_path"],
+      "properties": {
+        "version": { "type": "string", "const": "3.0" },
+        "generated_at": { "type": "string", "format": "date-time" },
+        "repository_path": { "type": "string" },
+        "agent": { "type": "string", "const": "qa-validator" }
+      }
+    },
+    "overall_score": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Calculated quality score"
+    },
+    "quality_rating": {
+      "type": "string",
+      "enum": ["excellent", "good", "fair", "needs-improvement"],
+      "description": "Categorical rating based on score"
+    },
+    "ready_for_use": {
+      "type": "boolean",
+      "description": "Whether the documentation is considered sufficient for release"
+    },
+    "score_breakdown": {
+      "type": "object",
+      "required": [
+        "file_reference_score",
+        "api_verification_score",
+        "structure_score",
+        "question_coverage_score",
+        "component_coverage_score",
+        "flow_coverage_score",
+        "cross_links_score",
+        "diagrams_score",
+        "markdown_syntax_score"
+      ],
+      "properties": {
+        "file_reference_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "api_verification_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "structure_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "question_coverage_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "component_coverage_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "flow_coverage_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "cross_links_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "diagrams_score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "markdown_syntax_score": { "type": "number", "minimum": 0, "maximum": 100 }
+      }
+    },
+    "question_coverage": {
+      "type": "object",
+      "required": ["total", "answered", "coverage_percent"],
+      "properties": {
+        "total": { "type": "integer" },
+        "answered": { "type": "integer" },
+        "coverage_percent": { "type": "number" },
+        "unanswered_questions": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "validation_details": {
+      "type": "object",
+      "properties": {
+        "documentation_files_checked": { "type": "integer", "minimum": 0 },
+        "file_references_total": { "type": "integer", "minimum": 0 },
+        "file_references_valid": { "type": "integer", "minimum": 0 },
+        "file_references_validated": { "type": "integer", "minimum": 0 },
+        "api_candidates_total": { "type": "integer", "minimum": 0 },
+        "apis_verified": { "type": "integer", "minimum": 0 },
+        "components_total": { "type": "integer", "minimum": 0 },
+        "components_covered": { "type": "integer", "minimum": 0 },
+        "flows_total": { "type": "integer", "minimum": 0 },
+        "flows_covered": { "type": "integer", "minimum": 0 },
+        "questions_total": { "type": "integer", "minimum": 0 },
+        "questions_covered": { "type": "integer", "minimum": 0 },
+        "cross_links_total": { "type": "integer", "minimum": 0 },
+        "cross_links_checked": { "type": "integer", "minimum": 0 },
+        "cross_links_valid": { "type": "integer", "minimum": 0 },
+        "structure_valid": { "type": "boolean" },
+        "core_files_present": { "type": "boolean" },
+        "broken_links": { "type": "integer" },
+        "mermaid_syntax_errors": { "type": "integer" }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "description", "fix"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "warning", "info"]
+          },
+          "description": { "type": "string" },
+          "location": { "type": "string" },
+          "fix": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/skills/octocode-documentation-writer/schemas/questions-schema.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/questions.json",
+  "title": "Engineer Questions Output",
+  "description": "Comprehensive questions generated for documentation coverage",
+  "type": "object",
+  "required": [
+    "metadata",
+    "summary",
+    "questions"
+  ],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": [
+        "version",
+        "generated_at",
+        "repository_path"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "const": "3.0"
+        },
+        "generated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "repository_path": {
+          "type": "string"
+        },
+        "agent": {
+          "type": "string",
+          "const": "engineer-questions"
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total_questions",
+        "by_category",
+        "by_priority"
+      ],
+      "properties": {
+        "total_questions": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "by_category": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_priority": {
+          "type": "object",
+          "properties": {
+            "critical": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "high": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "medium": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "low": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "questions": {
+      "type": "array",
+      "minItems": 10,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "question",
+          "category",
+          "priority",
+          "research_goal",
+          "files_to_examine",
+          "reason",
+          "documentation_target",
+          "research_strategy"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the question",
+            "pattern": "^[a-zA-Z0-9_-]+$"
+          },
+          "question": {
+            "type": "string",
+            "description": "The question to be answered in documentation"
+          },
+          "category": {
+            "type": "string",
+            "enum": [
+              "component-overview",
+              "component-responsibility",
+              "component-exports",
+              "component-internal",
+              "component-dependencies",
+              "flow-trigger",
+              "flow-execution",
+              "flow-error-handling",
+              "flow-data-transformation",
+              "flow-complexity",
+              "architecture-overview",
+              "architecture-patterns",
+              "architecture-layers",
+              "architecture-decisions",
+              "api-documentation",
+              "api-usage",
+              "api-parameters",
+              "api-examples",
+              "integrations",
+              "configuration",
+              "deployment",
+              "edge-cases",
+              "performance",
+              "security",
+              "testing",
+              "overview",
+              "technical-stack",
+              "development-setup",
+              "data-models",
+              "monitoring",
+              "design-decisions",
+              "feature",
+              "component",
+              "flow"
+            ]
+          },
+          "priority": {
+            "type": "string",
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ]
+          },
+          "research_goal": {
+            "type": "string",
+            "description": "What should be discovered when answering this question"
+          },
+          "files_to_examine": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            },
+            "description": "File paths or patterns to examine"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why this question is important for documentation"
+          },
+          "documentation_target": {
+            "type": "string",
+            "description": "The target documentation file that this question answers (e.g. 01-project-overview.md)"
+          },
+          "research_strategy": {
+            "type": "object",
+            "required": [
+              "approach",
+              "tools_to_use",
+              "expected_findings"
+            ],
+            "properties": {
+              "approach": {
+                "type": "string",
+                "description": "High-level research approach"
+              },
+              "tools_to_use": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string"
+                }
+              },
+              "expected_findings": {
+                "type": "string",
+                "description": "What information is expected to be found"
+              },
+              "documentation_target": {
+                "type": "string",
+                "description": "What should be documented based on findings"
+              }
+            }
+          },
+          "dependencies": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "IDs of questions that should be answered first"
+          },
+          "related_components": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Components related to this question"
+          },
+          "related_flows": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Flows related to this question"
+          }
+        }
+      }
+    }
+  }
+}

package/skills/octocode-documentation-writer/schemas/research-schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/research.json",
+  "title": "Research Findings Output",
+  "description": "Answers and context gathered for engineering questions",
+  "type": "object",
+  "required": [
+    "metadata",
+    "findings"
+  ],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "version",
+        "agent",
+        "total_questions_researched",
+        "repository_path"
+      ],
+      "properties": {
+        "generated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "version": {
+          "type": "string",
+          "const": "3.0"
+        },
+        "agent": {
+          "type": "string",
+          "const": "researcher"
+        },
+        "total_questions_researched": {
+          "type": "integer"
+        },
+        "repository_path": {
+          "type": "string"
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "question_id",
+          "status",
+          "answer",
+          "code_references"
+        ],
+        "properties": {
+          "question_id": {
+            "type": "string",
+            "description": "ID matching the question from questions.json"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "answered",
+              "partial",
+              "not_found",
+              "skipped"
+            ]
+          },
+          "answer": {
+            "type": "string",
+            "description": "Comprehensive answer to the question based on code evidence"
+          },
+          "code_references": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "file"
+              ],
+              "properties": {
+                "file": {
+                  "type": "string"
+                },
+                "line_start": {
+                  "type": "integer"
+                },
+                "line_end": {
+                  "type": "integer"
+                },
+                "snippet": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "related_symbols": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Functions, classes, or types relevant to this finding"
+          }
+        }
+      }
+    }
+  }
+}

package/skills/octocode-documentation-writer/schemas/state-schema.json

@@ -0,0 +1,222 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/state.json",
+  "title": "Orchestration State",
+  "description": "State tracking for documentation generation pipeline",
+  "type": "object",
+  "required": ["version", "repository_path", "phase", "started_at"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "3.0"
+    },
+    "repository_path": {
+      "type": "string"
+    },
+    "phase": {
+      "type": "string",
+      "enum": [
+        "initialized",
+        "discovery-analysis-running",
+        "discovery-analysis-complete",
+        "discovery-analysis-failed",
+        "engineer-questions-running",
+        "engineer-questions-complete",
+        "engineer-questions-failed",
+        "research-running",
+        "research-complete",
+        "research-failed",
+        "orchestrator-running",
+        "orchestrator-complete",
+        "orchestrator-failed",
+        "documentation-running",
+        "documentation-complete",
+        "documentation-partial",
+        "documentation-failed",
+        "qa-running",
+        "qa-complete",
+        "qa-failed",
+        "complete",
+        "failed"
+      ]
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "completed_at": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "current_agent": {
+      "type": ["string", "null"]
+    },
+    "status": {
+      "type": "string"
+    },
+    "completed_agents": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "discovery-analysis",
+          "engineer-questions",
+          "researcher",
+          "orchestrator",
+          "documentation-writer",
+          "qa-validator"
+        ]
+      }
+    },
+    "writer_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "critical_writer_id": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "retry_attempt": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "failed_writer_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "failed_writers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "successful_writers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "writers_completed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "warning": {
+      "type": "string"
+    },
+    "error": {
+      "type": "string"
+    },
+    "token_usage": {
+      "type": "object",
+      "properties": {
+        "discovery_analysis": {"type": "integer", "minimum": 0},
+        "engineer_questions": {"type": "integer", "minimum": 0},
+        "research": {"type": "integer", "minimum": 0},
+        "orchestrator": {"type": "integer", "minimum": 0},
+        "documentation": {"type": "integer", "minimum": 0},
+        "qa": {"type": "integer", "minimum": 0},
+        "total": {"type": "integer", "minimum": 0}
+      }
+    },
+    "retry_state": {
+      "type": "object",
+      "description": "Tracks retry attempts per phase to prevent data loss",
+      "properties": {
+        "discovery_analysis": {
+          "type": "object",
+          "properties": {
+            "attempts": {"type": "integer", "minimum": 0, "default": 0},
+            "max_attempts": {"type": "integer", "default": 3},
+            "partial_results": {"type": "array", "items": {"type": "string"}},
+            "last_error": {"type": "string"}
+          }
+        },
+        "engineer_questions": {
+          "type": "object",
+          "properties": {
+            "attempts": {"type": "integer", "minimum": 0, "default": 0},
+            "max_attempts": {"type": "integer", "default": 3},
+            "last_error": {"type": "string"}
+          }
+        },
+        "research": {
+          "type": "object",
+          "properties": {
+            "attempts": {"type": "integer", "minimum": 0, "default": 0},
+            "max_attempts": {"type": "integer", "default": 3},
+            "total_batches": {"type": "integer", "minimum": 0},
+            "completed_batches": {"type": "array", "items": {"type": "string"}},
+            "failed_batches": {"type": "array", "items": {"type": "string"}},
+            "last_error": {"type": "string"}
+          }
+        },
+        "orchestrator": {
+          "type": "object",
+          "properties": {
+            "attempts": {"type": "integer", "minimum": 0, "default": 0},
+            "max_attempts": {"type": "integer", "default": 3},
+            "last_error": {"type": "string"}
+          }
+        },
+        "documentation": {
+          "type": "object",
+          "properties": {
+            "attempts_per_writer": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "attempts": {"type": "integer", "minimum": 0},
+                  "max_attempts": {"type": "integer", "default": 3},
+                  "completed_files": {"type": "array", "items": {"type": "string"}},
+                  "last_error": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "qa": {
+          "type": "object",
+          "properties": {
+            "attempts": {"type": "integer", "minimum": 0, "default": 0},
+            "max_attempts": {"type": "integer", "default": 2},
+            "last_error": {"type": "string"}
+          }
+        }
+      }
+    },
+    "files_generated": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "qa_results": {
+      "type": ["object", "null"],
+      "properties": {
+        "overall_score": {"type": "integer", "minimum": 0, "maximum": 100},
+        "quality_rating": {
+          "type": "string",
+          "enum": ["excellent", "good", "fair", "needs-improvement"]
+        },
+        "ready_for_use": {"type": "boolean"},
+        "critical_gaps": {"type": "integer", "minimum": 0}
+      }
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["phase", "message", "timestamp"],
+        "properties": {
+          "phase": {"type": "string"},
+          "message": {"type": "string"},
+          "timestamp": {"type": "string", "format": "date-time"},
+          "recoverable": {"type": "boolean"}
+        }
+      }
+    }
+  }
+}