From Guidelines to Toolchain: Rebuilding claude-docs in One Day

I maintain 20+ open-source packages. Every one of them needs documentation. And every time I start a new project, I solve the same problems — folder structure, linting rules, release notes, badge standards.

claude-docs was supposed to fix that. But until today, it was just a set of guidelines and a slash command. Helpful, not enough.

So I blocked out a day to turn it into a proper toolchain. 8 commits, 20 files changed, +2,083 / -449 lines. Here's the before and after.

Documentation Guidelines

Before: Abstract rules about how docs should look. You read them, nodded, then did your own thing anyway.

After: Rewritten from scratch with concrete examples for 5 project types — Laravel packages, APIs, full-stack apps, CLI tools, and SDKs. Numbered folder conventions, progressive detail structure, ADR support, MermaidJS diagrams. Over 700 lines changed in the first commit alone.

The goal: if you can't figure out how to structure your docs after reading the guidelines, that's a bug.

Markdown Linting

Before: markdownlint was configured, but you had to run it file by file. Most of the time, people just skipped it.

After: One script, one command. lint.sh finds all markdown files, auto-detects your config, and lints everything in one pass. Add --fix to auto-correct.

~/.claude/lint.sh           # lint everything
~/.claude/lint.sh --fix     # lint & auto-fix

If linting takes effort, nobody lints. Now it doesn't.

Release Notes

Before: Manual. Copy commits from git log, reformat into markdown, paste into CHANGELOG. Every. Single. Time.

After: release-note.sh — a 300+ line script that parses your git log, categorizes commits by conventional prefixes, and generates structured markdown with summary tables and contributor lists.

~/.claude/release-note.sh                        # today's release note
~/.claude/release-note.sh --tldr                 # summary version
~/.claude/release-note.sh --since "1 week ago"   # custom date range
~/.claude/release-note.sh --output CHANGELOG.md  # write to file

This one went through three iterations in a single session — build, refactor, extend. The first version showed me what the second version needed. That's the natural rhythm for tooling work.

Badge Standards

Before: Some projects had badges, some didn't. No consistency.

After: Mandatory version and license badges for every project README. Copy-paste templates for 10 package registries (Packagist, npm, PyPI, crates.io, and more). Badge compliance tracked in the /docs health report.

Badges are the first thing people see on your repo. They signal you care. Making the standard easy to follow is what makes people actually follow it.

Project Auto-Detection

Before: PHP and Node only.

After: Supports Python, Ruby, Rust, Go, .NET, Java, Dart/Flutter, and Elixir. Run /docs scaffold <type> and get the right structure for your stack.

What /docs Can Do Now

After today's update, here's everything available under the /docs slash command in Claude Code:

Command	What It Does
/docs	Create new documentation structure (auto-detects your project type)
/docs reorganize	Reorganize existing docs into the numbered standard
/docs validate	Validate against standards and report issues
/docs update-toc	Update all README.md table of contents
/docs health	Generate documentation health report with badge compliance
/docs scaffold <type>	Scaffold from template: laravel, api, cli, sdk, fullstack
/docs release-note	Generate full release note from today's git log
/docs release-note --tldr	Generate summary release note

One command to rule them all. Pick what you need.

The Full Picture

One install command gets you everything:

curl -fsSL https://raw.githubusercontent.com/nasrulhazim/claude-docs/main/install.sh | bash

What You Get	What It Does
Guidelines	Concrete examples for 5 project types
lint.sh	Batch markdown linting with auto-fix
release-note.sh	Git log → structured release notes
/docs command	Scaffold, validate, health report, auto-detect
Badge templates	10 registries, 13 project types

Why This Matters

I'm a solo founder running Cleanique Coders. No docs team, no technical writer. What I have is tooling that enforces standards so I don't have to remember them.

Every hour spent on this saves ten hours of "how did we do docs in that project?" across the next year. If you maintain multiple repos — especially alone — standardize the boring stuff first.

The repo is open source. Take it, use it, tell me what's missing.

👉 github.com/nasrulhazim/claude-docs