octocode-cli 1.2.6 → 1.2.7

package/skills/octocode-documentation-writer/README.md

@@ -0,0 +1,113 @@
+<div align="center">
+  <img src="https://github.com/bgauryy/octocode-mcp/raw/main/packages/octocode-mcp/assets/logo_white.png" width="400px" alt="Octocode Logo">
+
+  <h1>Octocode Documentation Writer Skill</h1>
+
+  <p><strong>Repository Documentation Generator</strong></p>
+  <p>Production-ready pipeline • Intelligent orchestration • Conflict-free writing</p>
+
+  [![Skill](https://img.shields.io/badge/skill-agentskills.io-purple)](https://agentskills.io/what-are-skills)
+  [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE)
+
+</div>
+
+---
+
+## The Problem
+
+Agents struggle with writing documentation because:
+- **No context** — They miss the "big picture" of the codebase.
+- **Hallucinations** — They invent function names or behaviors.
+- **Conflicts** — Multiple agents overwriting the same files.
+- **Superficiality** — Generating generic "this function does X" docs.
+
+## The Solution
+
+**Octocode Documentation Writer** orchestrates specialized AI agents to:
+1.  **Discover** the codebase structure.
+2.  **Research** deep technical questions using **Octocode MCP** tools.
+3.  **Write** comprehensive documentation with exclusive file ownership.
+4.  **Validate** the output against the code.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-documentation-writer
+```
+
+### 🔌 Octocode MCP Setup
+
+This skill uses the **[Octocode MCP](https://github.com/bgauryy/octocode-mcp)** server for deep research capabilities (LSP, local search, etc.).
+
+Install via the CLI or add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "octocode": {
+      "command": "npx",
+      "args": ["-y", "octocode-mcp"],
+      "env": { "ENABLE_LOCAL": "true" }
+    }
+  }
+}
+```
+
+For authentication and full setup, see the [Octocode MCP docs](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md).
+
+---
+
+## ✨ Key Features
+
+- **True Parallel Execution**: Runs discovery, research, and writing phases in parallel for maximum speed.
+- **Host-Aware Execution**: Uses true parallel fan-out when the host supports it, with sequential fallback when it does not.
+- **Evidence-Based**: Research agents prove answers with code traces (LSP-powered via Octocode MCP) before writing.
+- **Conflict-Free Writing**: Writers are assigned exclusive file ownership to prevent overwrites.
+- **State Recovery**: Resume from any phase if interrupted.
+- **Dynamic Scaling**: Scales the number of agents based on discovered workload and question volume.
+
+## 🔄 Pipeline Phases
+
+The documentation generation process consists of 6 phases:
+
+1.  **Discovery & Analysis** (Parallel)
+    - 4 agents analyze language, components, dependencies, and flows simultaneously.
+    - Generates a comprehensive `analysis.json`.
+
+2.  **Engineer Questions** (Single)
+    - Generates deep technical questions based on the initial analysis.
+
+3.  **Research** (Parallel)
+    - Multiple researchers perform deep-dive code forensics to answer questions with evidence.
+    - Uses `analysis.json` plus **Octocode MCP** tools (LSP, Search) to trace code.
+
+4.  **Orchestrator** (Single)
+    - Groups questions and assigns exclusive file ownership to writers.
+    - Ensures no two writers work on the same file to avoid conflicts.
+
+5.  **Documentation Writers** (Parallel)
+    - Multiple writers synthesize research and write the actual documentation files (`*.md`).
+    - Produces core documentation and writer-owned supplementary files. `QA-SUMMARY.md` is generated by QA.
+
+6.  **QA Validator** (Single)
+    - Validates the generated documentation against the code, research findings, and initial questions.
+    - Generates a quality score and a QA summary.
+
+## 📂 Output
+
+The generated documentation will be saved in the `documentation/` directory within your repository.
+
+- `documentation/*.md`: The generated documentation files.
+- `documentation/QA-SUMMARY.md`: The phase-6 quality assurance summary.
+- `.octocode/documentation/{session-name}/`: Intermediate session state (analysis, research, assignments, QA metadata) - useful for debugging or resume flows.
+
+---
+
+## License
+
+MIT License © 2026 Octocode
+
+See [LICENSE](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE) for details.