jd-docs

name

jd-docs

description

Scaffold, validate, and maintain Johnny.Decimal documentation structure for software projects. Use when user mentions "Johnny Decimal", "J.D docs", "docs structure", "organize docs", "documentation layout", "scaffold docs", "docs migration", "generate index", "docs index", "add area", "classify docs", "move doc", editing files in numbered directories (00-*, 10-*, 20-*), or discussing documentation organization.

Johnny.Decimal Documentation

Scaffold, validate, and maintain Johnny.Decimal documentation structure with sensible defaults and per-project customization.

Quick Start

# Scaffold a new structure
uv run scripts/jd_init.py --dry-run   # Preview first
uv run scripts/jd_init.py             # Create docs/ with defaults
uv run scripts/jd_init.py --diataxis  # Include Diataxis areas (41-44)

# Validate existing structure
uv run scripts/jd_validate.py --dir docs

# Regenerate README index
uv run scripts/jd_index.py --dir docs

# Day-2: Add a new area
uv run scripts/jd_add_area.py --prefix 40 --name operations --dry-run

# Day-2: Classify unorganized files
uv run scripts/jd_classify.py docs/*.md
uv run scripts/jd_classify.py docs/*.md --diataxis  # With quadrant info

# Day-2: Move a file to an area
uv run scripts/jd_add.py docs/roadmap.md 00 --dry-run

See WORKFLOW.md for the full methodology.

Capabilities

• Scaffolding (jd_init.py) — Create J.D directory tree with README templates; supports --product for monorepo sub-trees, --init-config to generate .jd-config.json, and --diataxis to include Diataxis quadrant areas (41-44)
• Validation (jd_validate.py) — Check NN-kebab-case naming, detect orphan files, verify README presence per area; --strict for CI enforcement
• Index generation (jd_index.py) — Generate/update root README with table or tree index; preserves custom content via <!-- JD:INDEX:START/END --> markers
• Migration (Claude-driven) — Classify flat docs into J.D areas using naming heuristics, present a move plan, execute interactively

Day-2 Operations

• Add area (jd_add_area.py) — Create a new J.D area with prefix, name, README stub, config update, and auto re-index
• Classify (jd_classify.py) — Classify files into areas using keyword heuristics with confidence scoring (high/medium/low); --diataxis adds Diataxis quadrant column, --diataxis-move routes files to quadrant areas (41-44)
• Add/move file (jd_add.py) — Move a file to an area with auto-normalized kebab-case naming and cross-reference detection

Default Area Scheme

Prefix	Name	Purpose
00-	getting-started	Onboarding, setup, quick start, MVP
10-	product	Specs, features, roadmap, design, branding
20-	architecture	Tech decisions, system design, integration
30-	research	Spikes, investigations, reference material
90-	archive	Historical/deprecated docs

Gap at 40-80 reserved for per-project customization (e.g., 40-operations).

With --diataxis, areas 41-44 are added for Diataxis quadrants:

| 41- | tutorials | Tutorials — step-by-step lessons (Diataxis) | | 42- | how-to | How-to guides — practical tasks (Diataxis) | | 43- | reference | Reference — technical descriptions (Diataxis) | | 44- | explanation | Explanation — conceptual discussions (Diataxis) |

Config File (.jd-config.json)

Optional per-project override at project root:

{
  "version": 1,
  "root": "docs",
  "areas": { "00": "getting-started", "10": "product", "20": "architecture", "30": "research", "90": "archive" },
  "products": [],
  "ignore": ["adr", "*.pdf"],
  "readme_format": "table"
}

Create with uv run scripts/jd_init.py --init-config. All fields have sensible defaults.

Common Issues

Issue	Fix
uv not found	curl -LsSf https://astral.sh/uv/install.sh | sh or run with python3 scripts/jd_init.py
Orphan files in validation	Move to area dir, or add to "ignore" in .jd-config.json
Index appended at wrong position	Move <!-- JD:INDEX:START/END --> markers to desired location after first run
Low confidence on all files	Expand keywords in config or use Claude-driven classification

See TROUBLESHOOTING.md for all error scenarios.

References

• WORKFLOW.md — Full methodology (discovery, config, scaffold, validate, index, migrate, day-2)
• EXAMPLES.md — Real-world examples for all operations
• TROUBLESHOOTING.md — Error handling and debugging tips