brainharness-docs

Practical documentation structure templates for AI-assisted projects. Helps AI coding agents (and humans) organize project docs by size, audience, and freshness.

imageLicense: MIT

What it does

Answers the question every project eventually asks: where should this doc go?

Given a project, this skill:

1. Assesses project size (small / medium / large) using a simple rubric
2. Recommends a directory structure with templates for each size
3. Classifies existing docs by audience (agent, operator, user) and freshness (canonical, snapshot, archived)
4. Slims bloated CLAUDE.md/AGENTS.md by extracting reference material into dedicated files
5. Prevents drift with single-source-of-truth principles and doc metadata conventions

Works with any AI coding agent: Claude Code, OpenClaw, Codex CLI, Gemini CLI, Cursor, Copilot.

Quick Start

# Universal (npx skills)
npx skills add zning1994/brainharness-docs

# OpenClaw ClawHub
npx clawhub@0.23.3 install brainharness-docs

# Standalone
git clone https://github.com/zning1994/brainharness-docs

When to use

• Setting up docs for a new project
• Reorganizing a messy docs/ folder
• CLAUDE.md or AGENTS.md is over 250 lines
• Same information duplicated across multiple markdown files
• Not sure where a new doc should live
• Need to archive old design specs or research notes

Core Principles

1. Single Source of Truth

Every fact lives in exactly one place. Other docs link to it, never copy it.

2. CLAUDE.md Is a Routing Table

Keep CLAUDE.md under 250 lines. It tells AI agents where to find things, not what things are. Extract API tables, deploy procedures, and changelogs into docs/.

3. Organize by Audience + Freshness

4. No Cross-Doc Mirroring

After changes, update the one canonical doc. Not two, not three — one.

Project Size Templates

Small (< 5 source files)

project/
├── CLAUDE.md    # 50-100 lines
└── README.md

Medium (has API, deployment)

project/
├── CLAUDE.md    # 100-200 lines
└── docs/
    ├── reference/
    ├── design/
    └── plans/

Large (multi-service, continuous ops)

project/
├── CLAUDE.md    # 200-250 lines
└── docs/
    ├── reference/
    ├── runbooks/
    ├── guides/
    ├── product/
    ├── design/
    ├── plans/
    ├── research/
    ├── decisions/
    └── archive/

Document Metadata

Add to the top of any non-trivial doc:

---
status: canonical | snapshot | archived
audience: agent | operator | user | contributor
last_reviewed: YYYY-MM-DD
---

Anti-Patterns

Origin

Lessons learned from reorganizing ai-personal-system, a multi-agent AI operating system with 70+ API endpoints, 6 agents, and 39 skills. The AGENTS.md went from 800+ lines to 250, with zero information loss.

License

MIT

Codex and OpenAI plugins

The root plugin.json provides a portable package using the same skill source as Claude. Once the repository marketplace is available, install with codex plugin add brainharness-docs@brainharness. This plugin is not yet listed in the public ChatGPT plugin directory.

When creating an upload archive, materialize symlinks inside skills/brainharness-docs/ and include all referenced files.