octocode-cli 1.2.6 → 1.2.7

package/skills/octocode-documentation-writer/schemas/discovery-tasks.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "discovery-tasks.json",
+  "title": "Discovery Tasks Schema",
+  "description": "Schema for defining parallel discovery workflow structure with agents and aggregation",
+  "type": "object",
+  "properties": {
+    "phase": {
+      "type": "string",
+      "description": "The phase identifier for this discovery workflow",
+      "enum": ["discovery-analysis"]
+    },
+    "parallel_agents": {
+      "type": "array",
+      "description": "List of agents that run in parallel during discovery",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the agent",
+            "pattern": "^agent-[0-9]+[a-z]-[a-z]+(-[a-z]+)*$"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of what this agent discovers"
+          },
+          "critical": {
+            "type": "boolean",
+            "description": "Whether this agent's completion is critical for the workflow",
+            "default": true
+          },
+          "subagent_id": {
+            "type": "string",
+            "description": "Identifier used to spawn or reference this subagent",
+            "pattern": "^[0-9]+[a-z]-[a-z]+(-[a-z]+)*$"
+          }
+        },
+        "required": ["id", "description", "critical", "subagent_id"],
+        "additionalProperties": false
+      }
+    },
+    "aggregation": {
+      "type": "object",
+      "description": "Configuration for the aggregation step that combines parallel results",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the aggregation step"
+        },
+        "subagent_id": {
+          "type": "string",
+          "description": "Identifier for the aggregation subagent"
+        }
+      },
+      "required": ["description", "subagent_id"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["phase", "parallel_agents", "aggregation"],
+  "additionalProperties": false,
+  "default": {
+    "phase": "discovery-analysis",
+    "parallel_agents": [
+      {
+        "id": "agent-1a-language",
+        "description": "Language & Manifest Discovery",
+        "critical": true,
+        "subagent_id": "1a-language"
+      },
+      {
+        "id": "agent-1b-components",
+        "description": "Component Discovery",
+        "critical": true,
+        "subagent_id": "1b-components"
+      },
+      {
+        "id": "agent-1c-dependencies",
+        "description": "Dependency Mapping",
+        "critical": true,
+        "subagent_id": "1c-dependencies"
+      },
+      {
+        "id": "agent-1d-flows-apis",
+        "description": "Flow & API Discovery",
+        "critical": true,
+        "subagent_id": "1d-flows-apis"
+      }
+    ],
+    "aggregation": {
+      "description": "Aggregate parallel analysis results",
+      "subagent_id": "aggregation"
+    }
+  }
+}

package/skills/octocode-documentation-writer/schemas/documentation-structure.json

@@ -0,0 +1,373 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Documentation Structure Schema",
+  "description": "Centralized definition of rigid documentation structure for all octocode-documentation-writer agents and commands",
+  "version": "1.0.0",
+  "structure": {
+    "description": "Complete documentation structure with files and folders",
+    "core_files": {
+      "description": "Required core documentation files (numbered, sequential)",
+      "generated_by_default": "documentation-writer",
+      "files": [
+        {
+          "filename": "01-project-overview.md",
+          "title": "Project Overview",
+          "description": "Project summary, mission, users, what it does",
+          "required": true,
+          "order": 1,
+          "sections": [
+            "Project Purpose",
+            "Target Users",
+            "Key Features",
+            "Project Type",
+            "Primary Language",
+            "Key Flows"
+          ]
+        },
+        {
+          "filename": "02-technical-stack.md",
+          "title": "Technical Stack",
+          "description": "Complete technology inventory",
+          "required": true,
+          "order": 2,
+          "sections": [
+            "Languages",
+            "Frameworks",
+            "Databases",
+            "Message Queues",
+            "External Services",
+            "Build Tools",
+            "Key Dependencies"
+          ]
+        },
+        {
+          "filename": "03-development-setup.md",
+          "title": "Development Setup",
+          "description": "How to set up development environment",
+          "required": true,
+          "order": 3,
+          "sections": [
+            "Prerequisites",
+            "Installation Steps",
+            "Configuration",
+            "Common Commands",
+            "Troubleshooting"
+          ]
+        },
+        {
+          "filename": "04-api-reference.md",
+          "title": "API Reference",
+          "description": "Complete API reference with all endpoints/methods",
+          "required": true,
+          "order": 4,
+          "sections": [
+            "API Overview",
+            "Authentication",
+            "Endpoints",
+            "Request/Response Formats",
+            "Error Codes",
+            "Rate Limiting"
+          ]
+        },
+        {
+          "filename": "05-data-models.md",
+          "title": "Data Models",
+          "description": "Database schemas, data structures, relationships",
+          "required": false,
+          "order": 5,
+          "sections": [
+            "Database Schema",
+            "Core Entities",
+            "Relationships",
+            "Indexes",
+            "Migrations"
+          ]
+        },
+        {
+          "filename": "06-deployment.md",
+          "title": "Deployment",
+          "description": "Deployment processes and infrastructure",
+          "required": false,
+          "order": 6,
+          "sections": [
+            "Deployment Process",
+            "Infrastructure",
+            "Environment Variables",
+            "CI/CD Pipeline",
+            "Rollback Procedures"
+          ]
+        },
+        {
+          "filename": "07-monitoring-logging.md",
+          "title": "Monitoring & Logging",
+          "description": "Monitoring, logging, observability",
+          "required": false,
+          "order": 7,
+          "sections": [
+            "Logging Strategy",
+            "Monitoring Tools",
+            "Metrics",
+            "Alerting",
+            "Debugging"
+          ]
+        },
+        {
+          "filename": "08-design-decisions.md",
+          "title": "Design Decisions",
+          "description": "Key architectural and design decisions",
+          "required": true,
+          "order": 8,
+          "sections": [
+            "Architectural Decisions",
+            "Technology Choices",
+            "Trade-offs",
+            "Future Considerations"
+          ]
+        },
+        {
+          "filename": "09-design-patterns.md",
+          "title": "Design Patterns",
+          "description": "Maps architectural patterns to implementation",
+          "required": false,
+          "order": 9,
+          "sections": [
+            "Architectural Patterns",
+            "Creational Patterns",
+            "Structural Patterns",
+            "Behavioral Patterns",
+            "Anti-Patterns Avoided"
+          ]
+        },
+        {
+          "filename": "10-state-management.md",
+          "title": "State Management",
+          "description": "Data transition, persistence, and lifecycle",
+          "required": false,
+          "order": 10,
+          "sections": [
+            "Global State Strategy",
+            "Data Persistence",
+            "State Machines",
+            "Reactive Flows",
+            "Cache Invalidation"
+          ]
+        },
+        {
+          "filename": "11-testing-strategy.md",
+          "title": "Testing Strategy",
+          "description": "Validation logic and testing philosophies",
+          "required": false,
+          "order": 11,
+          "sections": [
+            "Testing Pyramid",
+            "Unit Testing",
+            "Integration Strategy",
+            "End-to-End Flows",
+            "Mocking Strategy"
+          ]
+        },
+        {
+          "filename": "12-security-compliance.md",
+          "title": "Security & Compliance",
+          "description": "Threat models, encryption, and data handling",
+          "required": false,
+          "order": 12,
+          "sections": [
+            "Threat Model",
+            "Authentication & Authorization",
+            "Data Encryption",
+            "Compliance Standards",
+            "Secret Management"
+          ]
+        },
+        {
+          "filename": "13-performance-benchmarks.md",
+          "title": "Performance Benchmarks",
+          "description": "Latency, throughput, and resource consumption",
+          "required": false,
+          "order": 13,
+          "sections": [
+            "Baseline Metrics",
+            "Load Testing Results",
+            "Resource Consumption",
+            "Bottlenecks",
+            "Optimization Targets"
+          ]
+        },
+        {
+          "filename": "14-contributing-guide.md",
+          "title": "Contributing Guide",
+          "description": "Rules of engagement for development",
+          "required": false,
+          "order": 14,
+          "sections": [
+            "Code of Conduct",
+            "Branching Strategy",
+            "Commit Conventions",
+            "Pull Request Process",
+            "Style Guide"
+          ]
+        },
+        {
+          "filename": "15-roadmap.md",
+          "title": "Roadmap",
+          "description": "Planned features and technical debt",
+          "required": false,
+          "order": 15,
+          "sections": [
+            "Upcoming Features",
+            "Known Issues",
+            "Technical Debt",
+            "Long-term Vision",
+            "Deprecation Plan"
+          ]
+        },
+        {
+          "filename": "16-glossary.md",
+          "title": "Glossary",
+          "description": "Domain-specific terminology definitions",
+          "required": false,
+          "order": 16,
+          "sections": [
+            "Domain Terms",
+            "Acronyms",
+            "System-Specific Concepts",
+            "Legacy Terms"
+          ]
+        }
+      ]
+    },
+    "supplementary_files": {
+      "description": "Optional supplementary documentation files",
+      "generated_by_default": "documentation-writer",
+      "files": [
+        {
+          "filename": "index.md",
+          "title": "Documentation Index",
+          "description": "Navigation hub for all documentation",
+          "required": false,
+          "generated_by": "documentation-writer"
+        },
+        {
+          "filename": "QA-SUMMARY.md",
+          "title": "QA Summary",
+          "description": "Quality validation report",
+          "required": false,
+          "generated_by": "qa-validator"
+        },
+        {
+          "filename": "AGENT.md",
+          "title": "Agent Navigation Guide",
+          "description": "Meta-documentation for AI agents explaining how to traverse and understand the documentation structure",
+          "required": false,
+          "generated_by": "documentation-writer"
+        }
+      ]
+    },
+    "folders": {
+      "description": "Documentation folder structure",
+      "directories": [
+        {
+          "name": "components",
+          "path": "components/",
+          "description": "Component-specific documentation",
+          "pattern": "*.md",
+          "required": false,
+          "purpose": "Detailed documentation for individual components/modules"
+        },
+        {
+          "name": "features",
+          "path": "features/",
+          "description": "Feature-specific documentation",
+          "pattern": "*.md",
+          "required": false,
+          "purpose": "In-depth documentation for major features"
+        },
+        {
+          "name": "flows",
+          "path": "flows/",
+          "description": "Flow documentation with diagrams",
+          "pattern": "*.md",
+          "required": false,
+          "purpose": "Step-by-step flows with Mermaid diagrams"
+        },
+        {
+          "name": "diagrams",
+          "path": "diagrams/",
+          "description": "Standalone diagram files",
+          "pattern": "*.md",
+          "required": false,
+          "purpose": "Mermaid diagrams for architecture, sequences, etc."
+        }
+      ]
+    },
+    "file_naming_conventions": {
+      "core_files": {
+        "pattern": "^\\d{2}-[a-z-]+\\.md$",
+        "description": "Two-digit prefix followed by kebab-case name",
+        "examples": [
+          "01-project-overview.md",
+          "02-technical-stack.md"
+        ]
+      },
+      "component_files": {
+        "pattern": "^[a-z-]+\\.md$",
+        "description": "Kebab-case filename",
+        "examples": [
+          "command-builders.md",
+          "execution-layer.md"
+        ]
+      },
+      "feature_files": {
+        "pattern": "^[a-z-]+\\.md$",
+        "description": "Kebab-case filename",
+        "examples": [
+          "binary-analysis.md",
+          "caching-layer.md"
+        ]
+      }
+    }
+  },
+  "usage": {
+    "description": "How agents and commands should reference this schema",
+    "agents": [
+      "discovery-analysis",
+      "engineer-questions",
+      "orchestrator",
+      "documentation-writer",
+      "qa-validator"
+    ],
+    "commands": [
+      "octocode-documentation-writer"
+    ],
+    "reference_example": {
+      "description": "Load and use this schema in agents/commands",
+      "code": "const docStructure = require('./schemas/documentation-structure.json');\nconst coreFiles = docStructure.structure.core_files.files;\nconst folders = docStructure.structure.folders.directories;"
+    }
+  },
+  "validation_rules": {
+    "description": "Rules for validating documentation completeness",
+    "rules": [
+      {
+        "rule": "all_core_files_present",
+        "description": "All required core files must be present",
+        "validation": "Check that all core_files with required=true exist"
+      },
+      {
+        "rule": "proper_naming",
+        "description": "Files must follow naming conventions",
+        "validation": "Match filenames against patterns in file_naming_conventions"
+      },
+      {
+        "rule": "folder_structure",
+        "description": "Supplementary files organized in correct folders",
+        "validation": "Components in components/, features in features/, etc."
+      },
+      {
+        "rule": "generated_by_respected",
+        "description": "Files must only be generated by the agent type declared in the structure schema",
+        "validation": "Honor generated_by on a file entry, otherwise fall back to generated_by_default for that file group"
+      }
+    ]
+  }
+}

package/skills/octocode-documentation-writer/schemas/partial-discovery-schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/partial-discovery.json",
+  "title": "Partial Discovery Output",
+  "description": "Schema for partial results from discovery sub-agents",
+  "type": "object",
+  "anyOf": [
+    {
+      "$comment": "1A: Language & Manifests",
+      "required": ["discovery"],
+      "properties": {
+        "discovery": {
+          "type": "object",
+          "required": ["primary_language", "is_monorepo", "project_type"],
+          "properties": {
+            "primary_language": { "type": "string" },
+            "is_monorepo": { "type": "boolean" },
+            "project_type": { "type": "string" },
+            "language_distribution": { "type": "object" },
+            "package_count": { "type": "integer" },
+            "packages": { "type": "array" }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "1B: Components",
+      "required": ["discovery"],
+      "properties": {
+        "discovery": {
+          "type": "object",
+          "required": ["components"],
+          "properties": {
+            "components": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["path", "type"],
+                "properties": {
+                  "path": { "type": "string" },
+                  "name": { "type": "string" },
+                  "type": { "type": "string" },
+                  "file_count": { "type": "integer" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "1C: Dependencies",
+      "required": ["architecture"],
+      "properties": {
+        "architecture": {
+          "type": "object",
+          "required": ["layers", "dependencies"],
+          "properties": {
+            "layers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "dependencies": {
+              "type": "object",
+              "properties": {
+                "internal": { "type": "array" },
+                "external": { "type": "array" }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "1D: Flows & APIs",
+      "required": ["flows", "apis"],
+      "properties": {
+        "flows": {
+          "type": "object",
+          "required": ["strategy", "flows"],
+          "properties": {
+            "strategy": { "type": "string" },
+            "flows": { "type": "array" }
+          }
+        },
+        "apis": {
+          "type": "object",
+          "required": ["components"],
+          "properties": {
+            "total_apis": { "type": "integer" },
+            "components": { "type": "array" }
+          }
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/partial-research.json",
+  "title": "Partial Research Output",
+  "description": "Schema for partial research results from parallel research agents",
+  "type": "object",
+  "required": [
+    "metadata",
+    "findings"
+  ],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": [
+        "version",
+        "generated_at",
+        "repository_path",
+        "batch_id"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "const": "3.0"
+        },
+        "generated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "repository_path": {
+          "type": "string"
+        },
+        "agent": {
+          "type": "string",
+          "const": "researcher"
+        },
+        "batch_id": {
+          "type": "string",
+          "description": "ID of the research batch (e.g. researcher-0)"
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "question_id",
+          "status",
+          "answer",
+          "code_references"
+        ],
+        "properties": {
+          "question_id": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "answered",
+              "partial",
+              "not_found",
+              "skipped"
+            ]
+          },
+          "answer": {
+            "type": "string"
+          },
+          "code_references": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "file"
+              ],
+              "properties": {
+                "file": {
+                  "type": "string"
+                },
+                "line_start": {
+                  "type": "integer"
+                },
+                "line_end": {
+                  "type": "integer"
+                },
+                "snippet": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "missing_context": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}