---

name: johnny-decimal description: > Helps organize files in a Johnny Decimal system at ~/Documents. Use this skill when filing documents, finding files, creating folders, taking notes about JD items, or understanding where something belongs in the system.

Johnny Decimal File Organization

Skill base directory: {baseDir}

This skill helps you work with the Johnny Decimal (JD) file system located at ~/Documents (or $XDG_DOCUMENTS_DIR).

Quick Reference

The system has 10 areas:

Area	Purpose
00-09 System	Meta-management (inbox, templates, scripts, archive)
10-19 Personal	People (Self, Spouse, Kids, Parents, Friends, Pets)
20-29 Finances	Banks, investments, credit, taxes, insurance
30-39 Home and Property	Homes, vehicles, major assets
40-49 Career and Education	Education, research, employers
50-59 Health and Wellness	General health resources (not personal records)
60-69 Hobbies and Recreation	Games, computing, creative works, travel
70-79 Legal and Records	Legal documents and archival records
80-89 Household and Services	Services, products, utilities, meals
90-99 Reference	Library, research, manuals, datasets

Structure Format

XX-XX Area Name/           # Area (decade range)
└── XX Category Name/      # Category (two digits)
    └── XX.YY Subcategory/ # Subcategory (ID)

Example path:

~/Documents/20-29 Finances/21 Banks/21.10 Example Bank/

Key Principles

1. One place for everything - Each item has exactly one correct location
2. Person-first for personal records - A spouse's health records go in 12 Spouse, not 50 Health
3. Purpose determines area - A bill goes in 27 Bills, not with the service provider
4. JDex is the brain - Notes and decisions live in 00.00 JDex for System

Finding Where Things Go

Before filing, consult:

• Flowchart: 00-09 System/00 System/00.00 JDex for System/flowchart.md
• Full structure: 00-09 System/00 System/00.00 JDex for System/overview.md

Or use your judgment with the filing hierarchy:

1. Is it about a specific person? → 10-19 Personal under their folder
2. Is it about yourself specifically? → 11 Self
3. Otherwise, match by purpose → Areas 20-99

Notes System

Notes about JD items live as markdown files in the JDex:

00-09 System/00 System/00.00 JDex for System/
├── overview.md      # System structure documentation
├── flowchart.md     # Filing decision tree
├── 31.14.md         # Notes about current home
├── 21.10.md         # Notes about a bank account
└── ...

Use jd-note to add timestamped entries to these files.

Naming Conventions

Folders:

• Areas: XX-XX Name (e.g., 20-29 Finances)
• Categories: XX Name (e.g., 21 Banks)
• Subcategories: XX.YY Name (e.g., 21.10 Example Bank)

Files:

• Date-prefixed for transient items: 2024-12-27_statement.pdf
• Descriptive for permanent items: policy_declaration.pdf
• Statements: statements/YYYY/MM.pdf or cc_MM.pdf for credit cards

Available Scripts

Scripts are located in {baseDir}/scripts/. Use the full path when invoking:

Script	Purpose
{baseDir}/scripts/jd-list.sh [ID]	List contents of an area, category, or ID
{baseDir}/scripts/jd-tree.sh [-L depth] [ID]	Show directory structure using tree
{baseDir}/scripts/jd-validate.sh <filename>	Check if filename follows conventions
{baseDir}/scripts/jd-mkdir.sh <category> <name>	Create a new subcategory folder (auto-numbers)
{baseDir}/scripts/jd-move.sh <file> <ID>	Move a file to a JD location (with validation)
{baseDir}/scripts/jd-note.sh [ID] [text]	Add a timestamped note (browse if no ID given)
{baseDir}/scripts/jd-read.sh [ID] [--edit]	Display notes for an ID (browse if no ID given)

Also available: jd <query> for navigation (in ~/bin/).

Interactive Features

When run by a human (not an agent), these commands have interactive modes:

• jd-note (no args) - Hierarchical browse (Area → Category → ID), then opens editor
• jd-note <ID> (without text) - Opens editor to write a note
• jd-read (no args) - Hierarchical browse (Area → Category → ID), then displays notes
• jd-read --edit (no args) - Hierarchical browse, then opens editor
• jd-read <ID> --edit - Opens the note file for editing

All properly handle TTY redirection for compatibility with any editor.

Agent Usage (--porcelain)

All scripts support a --porcelain flag for machine-readable output:

{baseDir}/scripts/jd-list.sh 21 --porcelain                # Full paths, no colors
{baseDir}/scripts/jd-tree.sh -L3 --porcelain               # Full structure, no colors
{baseDir}/scripts/jd-mkdir.sh 21 "Name" --porcelain        # Outputs created path
{baseDir}/scripts/jd-move.sh file.pdf 21.10 --porcelain    # Outputs destination path
{baseDir}/scripts/jd-note.sh 21.10 "text" --porcelain      # Adds note (text required)
{baseDir}/scripts/jd-read.sh 21.10 --porcelain             # Outputs note file path
{baseDir}/scripts/jd-validate.sh file.pdf --porcelain      # Machine-readable validation

When using these scripts as an agent:

• Always use --porcelain for reliable parsing
• Paths are absolute and suitable for further operations
• Errors go to stderr with exit code 1
• jd-note requires text argument in agent mode (no editor)
• jd-read --edit is not available in agent mode (requires TTY)
• All scripts auto-detect agent mode when stdout/stdin are not TTYs

Safety Rules

• Scripts will refuse to overwrite existing files
• Scripts validate paths before operations
• Always confirm destructive operations with the user
• When uncertain about filing location, ask rather than guess

Filing Inbox Documents

Files in the inbox (00.01) are typically scanned documents named by scan date (e.g., 20260127.pdf). When filing them:

1. Read the file to determine what it is
2. Decide where it goes using the flowchart and overview
3. ls the target directory to learn its naming conventions
4. Rename the file to match the existing pattern — see {baseDir}/references/NAMING.md
5. Move the file using jd-move or mv

The scan-date filename is never the final name. Always rename.

When to Explore

If you need current structure details not covered here, read:

1. overview.md in the JDex for full category breakdown
2. flowchart.md in the JDex for filing decisions
3. Use {baseDir}/scripts/jd-list.sh to see what exists in a location

References

For more detailed guidance, use the Read tool to load:

• {baseDir}/references/FILING-GUIDE.md - Detailed filing decisions and examples
• {baseDir}/references/NAMING.md - File and folder naming conventions