oss-docs

# OSS Documentation Skill

> Scaffold and audit documentation for open source projects.
> Based on patterns from [beads](https://github.com/steveyegge/beads) - a well-documented OSS project.

## Overview

This skill helps prepare repositories for open source release by:
1. Auditing existing documentation completeness
2. Scaffolding missing standard files
3. Generating content tailored to project type
4. Following proven patterns from successful OSS projects

## Commands

| Command | Action |
|---------|--------|
| `audit` | Check which OSS docs exist/missing |
| `scaffold` | Create all missing standard files |
| `scaffold [file]` | Create specific file (e.g., `scaffold CONTRIBUTING.md`) |
| `update` | Refresh existing docs with latest patterns |
| `validate` | Check docs follow best practices |

---

## Phase 0: Project Detection

Before scaffolding, detect project characteristics:

```bash
# Determine project type and language
PROJECT_NAME=$(basename $(pwd))
LANGUAGES=()

[[ -f go.mod ]] && LANGUAGES+=("go")
[[ -f pyproject.toml ]] || [[ -f setup.py ]] && LANGUAGES+=("python")
[[ -f package.json ]] && LANGUAGES+=("javascript")
[[ -f Cargo.toml ]] && LANGUAGES+=("rust")
[[ -f Chart.yaml ]] && LANGUAGES+=("helm")

# Detect project category
if [[ -f Dockerfile ]] && [[ -d cmd ]]; then
    PROJECT_TYPE="cli"
elif [[ -f PROJECT ]] || [[ -d config/crd ]]; then
    PROJECT_TYPE="operator"
elif [[ -f Chart.yaml ]]; then
    PROJECT_TYPE="helm"
elif [[ -d api ]] || [[ -d internal/server ]]; then
    PROJECT_TYPE="service"
else
    PROJECT_TYPE="library"
fi
```

---

## Subcommand: audit

Check which OSS documentation files exist:

### Required Files (Tier 1 - Core)

| File | Purpose | Status Check |
|------|---------|--------------|
| `LICENSE` | Legal terms | `[[ -f LICENSE ]]` |
| `README.md` | Project overview | `[[ -f README.md ]]` |
| `CONTRIBUTING.md` | How to contribute | `[[ -f CONTRIBUTING.md ]]` |
| `CODE_OF_CONDUCT.md` | Community standards | `[[ -f CODE_OF_CONDU