<div align="center">
  <img src="https://github.com/bgauryy/octocode/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/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/tree/main/skills/octocode-documentation-writer
```

### 🔌 Octocode MCP Setup

This skill uses the **[Octocode MCP](https://github.com/bgauryy/octocode)** 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/blob/main/docs/mcp/AUTHENTICATION.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/blob/main/LICENSE) for details.
