Manage Johnny.Decimal systems with AI-assisted inbox processing, classification, JDex maintenance, and system setup. Supports single and multi-system (SYS.AC.ID) configurations.
- GitHub stars
- 7
Install
/plugin install jd@jd-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add ngerakines/jd.
Contents
Discovered from sourceSkills 6
Johnny.Decimal Inbox Processor
This skill processes items in Johnny.Decimal 00.01 Inbox folders — reading
each item, classifying it against the system's JDex and folder structure, and
moving it to the correct ID location. When classification is ambiguous, it asks
the user to decide. It also extracts tasks, updates the JDex, and logs every
action.
Before processing, read references/jd-system-rules.md for the structural
conventions that govern all classification decisions.
1. Orientation: Discover the JD Environment
Before touching any files, build a mental map of the user's JD setup.
1.1 Locate the JD Root
The JD root folder is wherever the user's systems live. Common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/- A project-specific folder the user designates
If you don't know the root, ask the user. If the user says "process my inbox" without further context, check the most common locations above. If you find exactly one, confirm it. If you find multiple or none, ask.
1.2 Identify Systems
List the top-level folders under the JD root. Each folder whose name matches
the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal,
W20 Work, C40 Citywide).
If the user has a single system (no SYS prefix), that's fine — treat the entire JD root as one system.
1.3 Load Each System's JDex
For every system you'll process, read the JDex file at:
SYS/00-09 */00 */00.00 *JDex*
The JDex is the authoritative index of every area, category, and ID. It is your primary classification reference. If the JDex is missing or empty for a system, fall back to reading the folder structure directly — but flag this to the user as something that should be fixed.
1.4 Snapshot the Folder Structure
For each system, list the area folders, category folders, and ID folders to depth 3. This gives you the physical layout to validate against the JDex and to discover any folders not yet in the index.
2. Inbox Discovery
2.1 Locate Inboxes
Each system's inbox lives at:
SYS/00-09 */00 */00.01 Inbox/
List the contents of every inbox you find. If the user asked to process a specific system's inbox (e.g., "process my P10 inbox"), limit to that one.
2.2 Assess the Inbox
For each inbox, report to the user:
- Item count: How many files/folders are in the inbox
- Item types: File types present (
.md,.pdf,.jpg,.txt, etc.) - Date range: Earliest and latest date-prefixed items
If the inbox is empty, say so and move on. If it contains more than ~20 items, suggest processing in batches and ask the user how many to tackle.
3. Process Each Item
Work through inbox items one at a time (or in logical groups if items are clearly related, like a note and its accompanying photo). For each item:
3.1 Read and Understand the Item
- Text files (
.md,.txt): Read the full content. - PDFs: Read if possible; if not readable, use the filename and any available metadata.
- Images (
.jpg,.png): Describe what you see. If it's a photo of a document, extract what you can. - Other files: Use the filename, extension, and file size to infer purpose.
Summarize what the item is about in one sentence. This is your "item summary" and is used in the processing log.
3.2 Classify the Item
Classification follows a strict decision tree. At each level, you're choosing from a bounded set (≤10 options). This is where the JDex is critical.
Read references/classification-heuristics.md for detailed guidance on
ambiguous cases.
Step 1 — Which system? (Multi-system setups only)
If the user has multiple systems, determine which system the item belongs to. Signals include:
- Explicit system references in the content ("Citywide," "work," "personal")
- Content domain (tax docs → personal, buyer meeting notes → work)
- Filename patterns or prefixes the user may use
If ambiguous between systems, ask the user.
Step 2 — Which area?
Read the area list from the JDex. Choose the area whose description best
matches the item's content. Areas are broad domains (10-19 Home & property,
30-39 Money & legal, etc.).
If no area fits, this may indicate:
- The item belongs in a different system
- The system needs a new area (rare — flag for user decision, do not create)
- The item is miscategorized in the user's mind (ask)
Step 3 — Which category?
Within the chosen area, pick the category. Categories are collections of similar things. This is "where you work" — the most important classification decision.
Step 4 — Which ID?
Within the category, determine the specific ID folder:
- Existing ID matches: The item clearly belongs in an existing ID folder. Use it.
- +SUB match: If the category uses
+SUBextensions (e.g.,11.01+REDD), match the item to the correct sub-entry. - New ID needed: If no existing ID fits, you may need to create one. See §3.4.
3.3 Confidence Assessment
After classification, assess your confidence:
- High confidence (clear match, unambiguous): Proceed to filing.
- Medium confidence (reasonable match, but another location is plausible): State your recommendation and the alternative, then ask the user to confirm.
- Low confidence (genuinely unclear): Present the top 2–3 candidate locations with brief reasoning, and ask the user to choose.
The threshold: if you'd bet money on the classification, it's high confidence. If you'd want a second opinion, it's medium. If you're guessing, it's low.
When asking the user, be specific. Not "where should this go?" but rather:
This looks like a health insurance claim. I'd file it at P10.34.01 (Health insurance). Does that sound right, or does it belong somewhere else?
3.4 Creating New IDs
If an item needs a new ID (no existing ID in the category fits), follow these rules strictly:
- Never create a new area or category without explicit user approval. These are structural decisions that affect the whole system. Flag the need and ask.
- New IDs within an existing category are lower-stakes. You may propose a new ID, but always confirm with the user before creating it.
- Determine the next sequential ID number. Look at existing IDs in the
category. If the highest is
15.23, the next is15.24. If the category uses standard zeros (.00–.09reserved), the first content ID is.10or the next available number above.09. - Name the new ID clearly. Follow the pattern of existing IDs in the
category. JD ID folder names are:
AC.ID Description(e.g.,15.24 Trip to Portland). - After creating the folder, update the JDex with the new entry.
For +SUB entries, the process is similar but uses the +NNNN or +CODE
pattern established in that category.
3.5 Filing the Item
Once the destination is confirmed:
-
Rename the file with a date prefix if it doesn't already have one. Format:
YYYY-MM-DD Description.ext. Use today's date if the item has no inherent date. Use the item's date if it does (e.g., a receipt dated 2026-01-15). -
Move the file from the inbox to the destination ID folder.
-
If the item contains actionable tasks, extract them. See §4.
-
If the item is both a record and a task source, file the record AND extract the tasks. Don't choose one or the other.
3.6 Items That Don't Belong
Some inbox items are:
- Stale or irrelevant: Old notes that are no longer needed. Confirm with
the user, then move to
00.09 Archiveif that folder exists, or delete if the user prefers. - Duplicates: The same content already exists at the destination. Flag to the user and offer to delete the inbox copy.
- Cross-system references: The item belongs in System A but was captured in System B's inbox. Move it to System A's inbox (or directly to the correct ID if classification is clear), and note the cross-reference.
4. Task Extraction
Many inbox items contain embedded tasks — things the user needs to do. When you identify a task, extract it.
4.1 Identifying Tasks
Look for:
- Explicit action items ("need to send pricing," "follow up with Jordan")
- Deadlines ("by end of week," "before March 8")
- Commitments ("promised to deliver," "agreed to check on")
- Questions that need answers ("check with warehouse," "ask about delivery")
4.2 Task Format
Append extracted tasks to the system's task file at:
SYS/00-09 */00 */00.02 Tasks*
Each task should include:
- [ ] [Task description]
→ [JD reference: AC.ID or AC.ID+SUB] | Deadline: [date or "none"] | Source: [inbox item filename]
If the task file doesn't exist, create it. If the task file uses a different format, match the existing format.
4.3 Task Context
When possible, add context from the JD system to the task:
- Reference relevant IDs (e.g., "Pricing info in 31.03")
- Note related contacts or accounts
- Link to the filed record
5. Logging
After processing each item, append a log entry to:
SYS/00-09 */00 */00.03 Processing log.md
If this file doesn't exist, create it.
Log Entry Format
### YYYY-MM-DD HH:MM — Inbox Processing
| Item | Action | Destination | Notes |
|------|--------|-------------|-------|
| `filename.ext` | Filed | `AC.ID Description` | One-line summary |
| `filename2.md` | Filed + Task | `AC.ID+SUB` | Task added to 00.02 |
| `filename3.pdf` | Needs review | `00.04 Needs review` | Ambiguous; user asked to decide later |
| `filename4.txt` | Archived | `00.09 Archive` | Stale item, confirmed by user |
**Items processed**: N
**Tasks extracted**: N
**Needs review**: N
**New IDs created**: [list, or "none"]
6. JDex Maintenance
After all items are processed, verify the JDex:
- New entries: If any new IDs or +SUB entries were created during processing, confirm they've been added to the JDex.
- Orphan check (optional, suggest to user): Compare the JDex against the actual folder structure. Flag any folder that exists but isn't in the JDex, and any JDex entry whose folder doesn't exist.
7. Multi-System Processing
When the user says "process my inboxes" (plural) or doesn't specify a system:
- List all systems with non-empty inboxes.
- Report the item count per system.
- Ask whether to process all of them or just specific ones.
- Process each system's inbox in sequence. Keep system context separate — don't confuse P10's JDex with W20's categories.
- At the end, give a combined summary across all systems.
8. Interaction Principles
8.1 When to Ask vs. When to Act
- Act without asking: Filing an item to a clearly matching existing ID with proper date-prefix naming. This is routine and unambiguous.
- State and confirm in batch: When processing multiple items, you can propose a batch of filings and let the user approve them all at once rather than one at a time. Present a table: item → proposed destination.
- Ask before acting: Creating new IDs, creating new +SUB entries, archiving or deleting items, moving items between systems, any classification with medium or low confidence.
- Always ask: Creating new categories or areas. These are structural changes.
8.2 Batch Processing Mode
For inboxes with many items, offer batch mode:
- Read all items.
- Classify each one.
- Present a table of proposed actions.
- Let the user approve, modify, or flag specific items.
- Execute all approved actions.
- Handle flagged items individually.
This is faster than one-at-a-time for large inboxes while still giving the user control.
8.3 Learning from User Decisions
When the user corrects a classification or makes a non-obvious filing decision, note the reasoning. This helps you classify similar items in the future within the same session. For example, if the user says "actually, I keep all Northside stuff in 31.02, not by account," apply that pattern to subsequent Northside items.
9. Error Handling
- JDex missing: Warn the user. Offer to generate one from the folder structure. Process using folders as the reference, but note that a JDex should be created.
- Inbox folder missing: A system without
00.01 Inboxhas no inbox to process. Note this and move on. - Unreadable files: If a file can't be read (binary, corrupted, encrypted), log it, skip it, and tell the user.
- Filesystem errors: If a move fails (permissions, path issues), report the error, skip the item, and continue with the rest.
- JDex/folder mismatch: If the JDex says an ID exists but the folder doesn't (or vice versa), flag the inconsistency. Don't silently create or delete anything to "fix" it — the user decides.
10. Post-Processing Summary
After completing all inbox processing, present a summary:
Inbox processing complete.
[System name]: [N] items processed
→ [N] filed to existing IDs
→ [N] tasks extracted to 00.02
→ [N] new IDs created: [list]
→ [N] items need review (in 00.04)
→ [N] archived
[Repeat for each system processed]
JDex status: [up to date / N entries added / needs audit]
If any items were moved to "needs review," remind the user they're waiting.
Quick Reference: File Naming Convention
All files in JD ID folders use date-prefix naming:
YYYY-MM-DD Description.ext
- Use the item's inherent date when available (document date, receipt date, meeting date).
- Use the capture/creation date if no inherent date exists.
- Use today's date as a last resort.
- Keep descriptions short but specific. Match the style of existing files in the same folder.
- No special characters in filenames beyond hyphens and spaces.
Quick Reference: Standard Zeros
These reserved IDs exist (or may exist) in each category:
| ID | Purpose |
|---|---|
.00 | Category JDex / index |
.01 | Inbox |
.02 | Tasks / action items |
.03 | Templates (or processing log in system 00) |
.04 | Links / quick reference (or needs-review in system 00) |
.08 | Someday / parking lot |
.09 | Archive |
Not all systems use all standard zeros. Check what actually exists.
Johnny.Decimal JDex Audit
This skill compares a system's JDex (the authoritative index) against the actual folder structure on disk, identifying mismatches and suggesting fixes.
1. Locate the System
1.1 Find the JD Root
Check common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/
If the user specifies a system code (e.g., "audit my P10 system"), target that specific system. Otherwise, list all available systems and ask which to audit.
1.2 Load the JDex
Read the JDex file at:
SYS/00-09 */00 */00.00 *JDex*
Parse it into a structured list of areas, categories, and IDs. Each entry should capture:
- The AC.ID (or SYS.AC.ID) address
- The description/name
- Any +SUB entries
1.3 Snapshot the Filesystem
List all folders to depth 3 under the system root. Parse folder names to extract AC.ID addresses, area ranges, and category numbers.
2. Compare JDex vs. Filesystem
Run three checks:
2.1 Orphaned JDex Entries
JDex entries that have no corresponding folder on disk.
These indicate either:
- A folder was deleted without updating the JDex
- A planned ID that was never created
- A typo in the JDex entry
2.2 Undocumented Folders
Folders on disk that have no corresponding JDex entry.
These indicate either:
- A folder was created without updating the JDex
- The JDex fell out of sync during manual organization
- A folder created by another tool or process
2.3 Name Mismatches
JDex entries whose description doesn't match the folder name, or folders
whose name doesn't follow the expected AC.ID Description format.
3. Check +SUB Indexes
For categories that use +SUB extensions:
3.1 Locate Index Files
+SUB categories typically have an index file (e.g., 51.01 Open-source project index.md). Find these by looking for files matching *.md at the category
or ID level that contain +SUB listings.
3.2 Compare Index vs. Folders
- List all
+NNNNor+CODEfolders within the ID - Compare against the index file entries
- Flag missing or extra entries
4. Report Findings
Present a clear audit report to the user:
Report Format
## JDex Audit: [System name]
**Audit date:** YYYY-MM-DD
**JDex location:** [path]
**System root:** [path]
### Summary
| Check | Count |
|-------|-------|
| JDex entries | N |
| Filesystem folders | N |
| Orphaned JDex entries | N |
| Undocumented folders | N |
| Name mismatches | N |
| +SUB index issues | N |
### Orphaned JDex Entries (in JDex but no folder)
| AC.ID | Description | Suggested Action |
|-------|-------------|-----------------|
| 11.05 | Home improvement | Create folder or remove from JDex |
### Undocumented Folders (folder exists but not in JDex)
| Folder | Path | Suggested Action |
|--------|------|-----------------|
| 11.08 Garage storage | 10-19/11/11.08 | Add to JDex |
### Name Mismatches
| AC.ID | JDex says | Folder says | Suggested Action |
|-------|-----------|-------------|-----------------|
| 11.03 | Home insurance | Homeowners insurance | Reconcile names |
### +SUB Index Issues
| Category | Issue | Details |
|----------|-------|---------|
| 51.01 | Missing from index | +0004 folder exists, not in index |
5. Offer Fixes
After presenting the report, offer to fix issues:
Safe Fixes (do automatically with confirmation)
- Add undocumented folders to JDex: Append new entries matching the folder names.
- Update +SUB index files: Add missing entries to index files.
Requires User Decision
- Orphaned JDex entries: Ask whether to create the missing folder or remove the JDex entry.
- Name mismatches: Ask which name is correct (JDex or folder) and update the other.
Never Do Automatically
- Delete folders: Even if they appear orphaned, never delete without explicit user confirmation.
- Rename folders: Name changes can break references. Always confirm first.
- Create new areas or categories: These are structural decisions.
6. Regenerate JDex (Optional)
If the user requests it, offer to regenerate the JDex entirely from the folder structure:
- Walk the filesystem and build a complete list of areas, categories, and IDs.
- Preserve any JDex-only metadata (cross-system references, notes, +SUB descriptions) from the existing JDex.
- Write the new JDex, merging filesystem reality with JDex metadata.
- Present the result for user approval before overwriting.
Warning: Regeneration loses any JDex entries that don't have corresponding folders. Always confirm before proceeding.
7. Multi-System Audit
When auditing multiple systems:
- Audit each system independently.
- Present per-system reports.
- Optionally check cross-system references: if P10.34.01 is referenced by F50.32.01, verify that both the source and the reference exist.
- Provide a combined summary at the end.
Johnny.Decimal Next Action Dashboard
This skill creates a unified, prioritized view of everything requiring attention
across all Johnny.Decimal systems. It combines active tasks (from todo.txt),
unprocessed inbox items, and items needing review into a single report ordered
from most urgent to least urgent, followed by a "coming up" section for items
approaching actionability.
This skill is read-only — it never modifies any files. It reads and reports.
For task parsing rules, read ../jd-task-manager/references/jdtodo-spec.md
(the jdtodo.txt format specification).
1. Orientation: Discover the JD Environment
Before generating the report, build a mental map of the user's JD setup.
1.1 Locate the JD Root
The JD root folder is wherever the user's systems live. Common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/- A project-specific folder the user designates
If you don't know the root, ask the user. If the user says "what should I do next" without further context, check the most common locations above. If you find exactly one, use it. If you find multiple or none, ask.
1.2 Identify Systems
List the top-level folders under the JD root. Each folder whose name matches
the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal,
W20 Work).
If the user has a single system (no SYS prefix), treat the entire JD root as one system.
If the user specified a system code as an argument (e.g., "next actions for P10"), limit scanning to that system only.
1.3 Load Each System's JDex
For every system you'll scan, read the JDex file at:
SYS/00-09 */00 */00.00 *JDex*
The JDex is needed to enrich task displays with human-readable descriptions
for +AC.ID references. If the JDex is missing, you can still generate the
report but cannot enrich JD codes — note this in the summary.
2. Scan Data Sources
For each system, locate and read these data sources. If a source doesn't exist, skip it and note the absence.
2.1 Active Tasks — 00.02 Tasks/todo.txt
Read and parse todo.txt using jdtodo.txt format rules (see the jdtodo-spec
reference). For each task, extract:
- State (incomplete, complete, cancelled)
- Priority (
(A)through(Z), or none) - Creation date
- Description
- Contexts (
@context) - Projects (
+project,+AC.ID) - Key:value pairs (
due:,before:,t:,after:,id:,dep:,rec:,h:) - Notes (after
---)
Filter for actionable tasks. A task is actionable if ALL of these are true:
- It is incomplete (not
xor~) - It is not hidden (
h:1absent) - Its threshold date has passed or is absent (
t:date <= today, or not:) - Its
after:date has passed or is absent (after:date <= today, or noafter:) - It does not have
@somedaycontext - It does not have
due:someday - All
dep:references point to completed tasks (or the referencedid:does not exist in the active task list)
Track separately:
- Blocked tasks: Incomplete tasks whose
dep:points to an incomplete task. Count these for the summary but do not include in the main report. - Waiting tasks: Tasks with
@waitingcontext that are otherwise actionable. Include them in their normal bucket but count them separately for the summary.
2.2 Inbox — 00.01 Inbox/
List the contents of the inbox folder. Do NOT read or classify individual items — that is the inbox processor's job. Collect:
- Total item count
- File types present (
.md,.pdf,.jpg, etc.) - Date of the most recently added item (from filesystem metadata or date-prefix in filename)
If the inbox is empty, skip this data source entirely.
2.3 Needs Review — 00.04 Needs review/
List items in the needs-review folder. For each item, collect:
- Filename
- Date added (from date-prefix in filename, or filesystem metadata)
If the folder doesn't exist or is empty, skip this data source.
2.4 Someday — 00.02 Tasks/someday.txt
Count the number of tasks in someday.txt (if it exists). This is for the
summary statistics only — do not include someday tasks in the report body.
Also count tasks with @someday or due:someday in todo.txt that were
excluded by the actionability filter.
2.5 Coming Up — Future Threshold Tasks
Identify tasks that are NOT yet actionable but will become actionable within the next 14 days:
- Tasks with
t:YYYY-MM-DDwhere the date is > today AND <= today + 14 days - Tasks with
after:YYYY-MM-DDwhere the date is > today AND <= today + 14 days
These are not blocked or someday — they're simply waiting for their visibility window to open.
3. Categorize into Priority Buckets
Place each item into exactly one bucket — the highest-priority bucket it qualifies for. A task that qualifies for multiple buckets appears only in the first matching one.
3.1 Bucket Definitions
Process in this order (first match wins):
Bucket 1 — Overdue
Actionable tasks where due: or before: date is before today.
Show how many days overdue each task is.
Bucket 2 — Due Today
Actionable tasks where due: or before: date equals today.
Bucket 3 — Inbox
Unprocessed items in 00.01 Inbox/ folders.
Shown as a count per system, not individual items.
Bucket 4 — Needs Review
Items in 00.04 Needs review/ folders.
Shown as individual items with filenames.
Bucket 5 — High Priority
Actionable tasks with (A) priority that did not land in Overdue or Due Today.
Bucket 6 — Due This Week
Actionable tasks where due: or before: is within the next 7 days (after
today, up to and including today + 7 days). Excludes tasks already placed in
a higher bucket.
Bucket 7 — Other Actionable
All remaining actionable tasks — (B) through (Z) priority and unprioritized
tasks that did not land in any bucket above.
Bucket 8 — Coming Up
Tasks with t: or after: dates within the next 14 days that are not yet
actionable. These are shown to help the user prepare.
3.2 Sorting Within Buckets
Within each bucket, sort tasks by:
- Priority —
(A)first, then(B), then(C), ..., then unprioritized last - Due date — earliest first (tasks with no due date sort last)
- Creation date — oldest first
3.3 Empty Buckets
If a bucket has zero items, omit that section entirely from the report. Only show sections that have content.
4. Generate the Report
4.1 Report Header
## Next Actions
**Date:** YYYY-MM-DD
**Systems:** [comma-separated system names, e.g., P10 Personal, W20 Work]
If scanning a single system, omit the "Systems" line and use the system name in the header:
## Next Actions — P10 Personal
**Date:** YYYY-MM-DD
4.2 Overdue Section
### Overdue (N)
| Pri | Task | Due | Overdue |
|-----|------|-----|---------|
| (A) | [P10] Submit quarterly tax estimate +N42.13.02 @laptop | 2026-02-05 | 5 days |
| (B) | [P10] Review tuition bill +V06.31.02 @laptop | 2026-02-08 | 2 days |
Show the [SYS] prefix only when displaying multiple systems.
4.3 Due Today Section
### Due Today (N)
| Pri | Task |
|-----|------|
| (A) | [W20] Respond to P0 incident follow-up +G24.21.05 @work |
4.4 Inbox Section
### Inbox (N items)
| System | Items | Newest |
|--------|-------|--------|
| P10 Personal | 8 items (.md, .pdf, .jpg) | 2026-02-09 |
| W20 Work | 3 items (.md, .txt) | 2026-02-08 |
Run `/jd:process-inbox` to classify and file these items.
For single-system reports, simplify:
### Inbox (8 items)
8 unprocessed items (.md, .pdf, .jpg). Newest: 2026-02-09.
Run `/jd:process-inbox P10` to classify and file these items.
4.5 Needs Review Section
### Needs Review (N items)
| System | Item | Date |
|--------|------|------|
| P10 | 2026-01-28 Meeting notes.md | Jan 28 |
| W20 | 2026-02-03 Budget spreadsheet.xlsx | Feb 3 |
4.6 High Priority Section
### High Priority (N)
| Task | Due |
|------|-----|
| [P10] Clean out garage +GarageSale +N42.12.05 | 2026-05-01 |
| [W20] Review contract terms +G24.31.05 @laptop | 2026-02-15 |
4.7 Due This Week Section
### Due This Week (N)
| Pri | Task | Due |
|-----|------|-----|
| (B) | [P10] Schedule dentist for Hannah @phone | Feb 12 |
| (B) | [P10] Water all houseplants @home | Feb 11 |
4.8 Other Actionable Section
### Other Actionable (N)
| Pri | Task | Due |
|-----|------|-----|
| (B) | [P10] Sort items for garage sale +GarageSale | Feb 20 |
| (C) | [W20] Update project documentation @laptop | — |
| — | [P10] Update emergency contacts | — |
Show — for tasks with no due date.
4.9 Coming Up Section
### Coming Up (next 14 days)
| Task | Actionable | Due |
|------|------------|-----|
| [P10] Renew car registration +N42.12.01 | Jun 1 (in 5 days) | Jun 30 |
| [W20] Start Q2 planning +G24.21.02 | Feb 20 (in 10 days) | Mar 1 |
These tasks are not yet actionable but will become visible soon.
Show both the date the task becomes actionable (t: or after: date) and its
due date (if any). Include the "in N days" relative label.
4.10 JD Code Enrichment
When displaying tasks with +AC.ID or +SYS.AC.ID project tags, look up the
code in the relevant system's JDex. If found, you may append the description
after the task or use it in the table.
For example, if N42.13.02 maps to "Tax returns & estimates" in the JDex:
| (A) | Submit quarterly tax estimate +N42.13.02 @laptop | 2026-04-15 |
The JD code itself is usually enough context. Only add the description if the task text alone doesn't make the purpose clear.
4.11 Multi-System Display
When showing tasks from multiple systems:
- Prefix each task with
[SYS](e.g.,[P10],[W20]) - Group inbox and needs-review items by system in their tables
- Include all systems in the summary
When showing a single system:
- Omit the
[SYS]prefix - Omit per-system grouping in inbox/review tables
4.12 Summary
Always end the report with a summary section:
### Summary
| | Count |
|--|-------|
| Overdue | 2 |
| Due today | 1 |
| Inbox items | 11 |
| Needs review | 2 |
| High priority | 2 |
| Due this week | 3 |
| Other actionable | 8 |
| **Total actionable** | **16** |
| | |
| Blocked | 3 |
| Waiting (@waiting) | 2 |
| Someday | 5 |
| Coming up (14 days) | 2 |
**Recommended focus:** [one sentence suggesting where to start]
The "Recommended focus" line should follow this logic:
- If overdue tasks exist: "Start with the N overdue tasks."
- Else if due-today tasks exist: "Handle the N tasks due today."
- Else if inbox has items: "Process inbox to surface any hidden urgencies."
- Else if high-priority tasks exist: "Focus on the N high-priority items."
- Otherwise: "No urgent items. Good time for a review or inbox check."
5. Filtering
The user may request a filtered view. Apply the filter AFTER scanning all data sources but BEFORE bucketing.
5.1 Filter by System
"next actions for P10" — Only scan the specified system.
5.2 Filter by Context
"what can I do @phone" — Only include tasks with the specified context. Inbox and needs-review items are still shown (they may contain relevant work).
5.3 Filter by Project
"what's next for +GarageSale" — Only include tasks with the specified project tag. Inbox and needs-review items are omitted (they haven't been classified).
5.4 Filter by Timeframe
"what's due this week" — Only include tasks in the Overdue, Due Today, and Due This Week buckets. Omit inbox, needs review, and lower-priority buckets.
6. Interaction Principles
6.1 Read-Only
This skill never modifies files. It reads task files, inbox contents, and needs-review items, then generates a report. No writes, no moves, no edits.
6.2 No Duplicate Work
Do not read inbox item contents or classify them — that's the inbox processor's job. Only count items and note their presence.
Do not modify task priorities or due dates — that's the task manager's job.
6.3 Actionable Suggestions
After the report, suggest relevant next steps using other skills:
- If inbox has items: "Run
/jd:process-inboxto classify inbox items." - If overdue tasks exist: "Use
/jd:manage-tasksto reschedule or complete overdue tasks." - If someday count is high: "Use
/jd:manage-tasks reviewto review someday items."
6.4 Repeat Invocations
If the user asks for the report again during the same session, regenerate it fresh — task states may have changed.
7. Error Handling
7.1 Missing Task Files
If 00.02 Tasks/todo.txt doesn't exist for a system:
- Check if
00.02 Tasks.mdexists (legacy format). If so, note it and suggest migration via/jd:manage-tasks. - If nothing exists, note "No task files found for [system]" in the summary.
7.2 Missing Inbox or Review Folders
If 00.01 Inbox/ or 00.04 Needs review/ doesn't exist, simply omit that
data source. Do not warn about structural absence — not all systems use all
standard zeros.
7.3 Unparseable Tasks
If a task line cannot be parsed:
- Include it in the report with a
[parse error]flag - Do not skip it — the user should know it exists
- Continue processing remaining tasks
7.4 JDex Not Found
If a system's JDex is missing:
- Generate the report without JD code enrichment
- Note in the summary: "JDex not found for [system] — JD codes not enriched."
7.5 No Data Found
If all data sources are empty across all systems:
- Report "Nothing to do!" with a clean summary showing all zeros
- Suggest: "Good time to check if anything needs capturing."
Quick Reference: Priority Buckets
| Order | Bucket | Source | Criteria |
|---|---|---|---|
| 1 | Overdue | todo.txt | due: or before: < today |
| 2 | Due Today | todo.txt | due: or before: = today |
| 3 | Inbox | 00.01 Inbox/ | Any items present |
| 4 | Needs Review | 00.04 Needs review/ | Any items present |
| 5 | High Priority | todo.txt | (A) tasks not in above |
| 6 | Due This Week | todo.txt | due: or before: within 7 days |
| 7 | Other Actionable | todo.txt | All remaining actionable |
| 8 | Coming Up | todo.txt | t: or after: within 14 days |
Quick Reference: Actionability Criteria
A task is actionable if ALL true:
- Not completed (
x) or cancelled (~) - Not hidden (
h:1absent) - Threshold passed (
t:<= today, or not:) - After date passed (
after:<= today, or noafter:) - No
@somedaycontext - No
due:someday - All
dep:resolved (blocking tasks completed or absent)
Johnny.Decimal +SUB Index Manager
This skill maintains +SUB index files within categories that use the
AC.ID+NNNN or AC.ID+CODE extension pattern. It keeps index files in
sync with the actual +SUB folders and helps create new entries.
1. Understand +SUB Extensions
+SUB extends the AC.ID notation for items that repeat across many instances
within a single ID.
Numeric +SUB: AC.ID+NNNN
Zero-padded four-digit sequential number:
53.01+0001 weather-api
53.01+0002 task-runner
53.01+0003 auth-dashboard
Named +SUB: AC.ID+CODE
Short alphanumeric code:
11.01+REDD The Red Door
11.01+OAKS Oak Street Cafe
11.01+RIVR Riverside Grill
When Each Format is Used
| Numeric +NNNN | Named +CODE |
|---|---|
| Items are primarily sequential | Items have natural short codes |
| No inherent abbreviation | Abbreviations are obvious and useful |
| Expect many entries (20+) | Expect fewer, memorable entries |
| Example: projects, trips, campaigns | Example: accounts, venues, people |
2. Locate +SUB Categories
2.1 Find the System
Check common JD root locations and identify the target system. If the user specifies a system code and category, go directly there. Otherwise, scan for +SUB categories.
2.2 Identify +SUB Categories
A category uses +SUB if it contains folders matching the pattern:
AC.ID+NNNN Description/
AC.ID+CODE Description/
Scan the system's categories and list those with +SUB folders.
2.3 Find the Index File
Each +SUB category should have an index file. Common patterns:
AC.ID [Category] index.md(e.g.,51.01 Open-source project index.md)AC.00 [Category] index.md(e.g.,51.00 Projects area index.md)
If no index file exists, offer to create one.
3. Scan Existing Entries
List all +SUB folders within the target category/ID. For each entry, capture:
- The +SUB identifier (number or code)
- The description (from folder name)
- Whether the folder contains content or is empty
- Creation date (from folder metadata or earliest file date)
4. Update the Index
4.1 Index File Format
The index file should list every +SUB entry with its identifier, name, creation date, and status:
# [Category name] Index
| +SUB | Name | Created | Status |
|------|------|---------|--------|
| +0001 | weather-api | 2025-06-01 | active |
| +0002 | task-runner | 2025-08-15 | active |
| +0003 | auth-dashboard | 2025-11-01 | archived |
For named +SUB:
# [Category name] Index
| +SUB | Name | Created | Status |
|------|------|---------|--------|
| +REDD | The Red Door | 2025-01-10 | active |
| +OAKS | Oak Street Cafe | 2025-03-22 | active |
| +RIVR | Riverside Grill | 2025-05-01 | active |
4.2 Sync Process
- Read the existing index file (if it exists).
- Compare index entries against actual +SUB folders.
- Add any folders that are missing from the index.
- Flag any index entries whose folders don't exist.
- Update the index file with the reconciled list.
4.3 Preserve Existing Format
If the user's index file uses a different format than the template above, match their existing format. Don't impose a new structure on an established index.
5. Create New +SUB Entries
When the user wants to add a new entry:
5.1 Determine the Next Identifier
For numeric +SUB:
- List all existing +NNNN entries in the category.
- Find the highest number.
- The next entry is that number + 1, zero-padded to 4 digits.
- Example: highest is
+0003→ next is+0004.
For named +SUB:
- Ask the user for the entry name.
- Derive a short code (typically 4 uppercase letters from the name).
- Verify the code doesn't conflict with existing entries.
- Example: "Midnight Sun Brewing" →
+MSUN.
5.2 Create the Folder
Create the +SUB folder:
AC.ID+NNNN Description/
or:
AC.ID+CODE Description/
5.3 Update the Index
Append the new entry to the index file.
5.4 Update the JDex
Add the new +SUB entry to the system's JDex under its parent ID:
- 53.01 Open-source projects
- 53.01+0001 weather-api
- 53.01+0002 task-runner
- 53.01+0003 auth-dashboard
- 53.01+0004 [new entry] ← added
6. Archiving +SUB Entries
When a +SUB entry is no longer active:
- Update the status in the index file from "active" to "archived".
- Do not move or delete the folder — archived entries stay in place.
- Optionally note the archive date in the index.
- The folder and its contents remain accessible for reference.
7. Reporting
After any update, present a summary:
+SUB Index Update: [Category name]
Entries: N total (N active, N archived)
Added: [list of new entries, or "none"]
Issues: [list of mismatches, or "none"]
Next available number: +NNNN
Johnny.Decimal System Setup
This skill creates a new Johnny.Decimal system from scratch — building the folder structure, standard zeros, and initial JDex based on the user's needs.
1. Gather Requirements
Before creating anything, understand what the user needs.
1.1 Single or Multi-System?
Ask the user:
- Single system: One organizational domain (e.g., just personal life, or
just work). No system prefix needed — folders use plain
AC.IDnotation. - Multi-system: Multiple distinct domains (e.g., personal + work, or
personal + work + child). Each system gets a
SYSprefix using the[A-Z][0-9][0-9]format.
If the user already has JD systems, check the existing root to avoid conflicts.
1.2 System Identity
For each system to create, gather:
- System code (multi-system only): A three-character
[A-Z][0-9][0-9]identifier. Encourage memorable codes (e.g.,P10for personal,W20for work). The code should be visually distinctive. - System name: A plain-English name (e.g., "Personal", "Work", "Jamie").
- Root location: Where the system will live on disk. Common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/
1.3 Areas and Categories
Walk the user through defining their areas. Provide guidance:
- Maximum 10 areas (including
00-09 System) - Each area covers a major life/work domain
- Fewer areas is better — compression over granularity
- Area
00-09is always created automatically for system management
For each area, ask about categories:
- Maximum 10 categories per area
- Categories are "where you work" — collections of similar things
- Category names should be short and clear
For each category, ask if they have specific IDs in mind, or if they'll create IDs as content arrives.
2. Create the Folder Structure
2.1 System Root
Create the system root folder:
- Single system:
[Root]/(e.g.,~/JD/) - Multi-system:
[Root]/SYS Name/(e.g.,~/JD/P10 Personal/)
2.2 Area Folders
Create area folders using the format AC-range Description:
00-09 System
10-19 [Area name]
20-29 [Area name]
...
2.3 Category Folders
Within each area, create category folders using the format AC Description:
00 System management
01 [Category name]
11 [Category name]
12 [Category name]
...
2.4 Standard Zeros (System Level)
Always create these in 00-09 System/00 System management/:
| Folder | Purpose |
|---|---|
00.00 JDex.md | Master index (file, not folder) |
00.01 Inbox/ | Unsorted capture bucket |
00.02 Tasks.md | Action items and follow-ups (file) |
00.03 Processing log.md | Record of inbox processing sessions (file) |
Optionally create if the user wants them:
| Folder | Purpose |
|---|---|
00.04 Needs review/ | Items awaiting user decision |
00.08 Someday/ | Non-urgent ideas and parking lot |
00.09 Archive/ | Completed or stale items |
2.5 ID Folders
If the user specified initial IDs during requirements gathering, create them
using the format AC.ID Description:
11.01 Mortgage & title/
11.02 Property tax/
11.03 Homeowners insurance/
3. Generate the JDex
Create 00.00 JDex.md with a complete listing of every area, category, and
ID in the system.
JDex Format
# [SYS] JDex
## 00-09 System
- 00.00 JDex ← this file
- 00.01 Inbox
- 00.02 Tasks
- 00.03 Processing log
## 10-19 [Area name]
### 11 [Category name]
- 11.01 [ID description]
- 11.02 [ID description]
### 12 [Category name]
- 12.01 [ID description]
## 20-29 [Area name]
...
JDex Rules
- Every folder that exists must have a JDex entry
- Every JDex entry must have a corresponding folder
- +SUB entries are listed inline under their parent ID
- Cross-system references use arrow notation:
→ P10.34.01
4. Initialize Task and Log Files
4.1 Tasks File
Create 00.02 Tasks.md:
# [System name] Tasks
Tasks extracted during inbox processing and daily use.
---
<!-- Add tasks below this line -->
4.2 Processing Log
Create 00.03 Processing log.md:
# [System name] Processing Log
Record of inbox processing sessions.
---
<!-- Processing entries will be appended below -->
5. Verification
After creating the structure:
- List the complete folder tree to depth 3 and present it to the user for review.
- Display the JDex so the user can verify all entries are correct.
- Confirm iCloud sync (if applicable): Verify folders appear correctly.
- Note next steps: Suggest the user start capturing items into their
inbox and run
/jd:process-inboxwhen ready.
6. Multi-System Considerations
When setting up multiple systems at once:
- Each system gets its own independent JDex
- Each system gets its own standard zeros
- Cross-system references should be noted during setup if known (e.g., "F50.32.01 will reference P10.34.01 for health insurance")
- Suggest the user set up one system fully before moving to the next
7. Templates for Common System Types
Offer these as starting points when the user isn't sure what areas to create:
Personal Life System
00-09 System
10-19 Home & property
20-29 Family & relationships
30-39 Money & legal
40-49 Health & wellness
50-59 Projects & hobbies
60-69 Travel & experiences
Work System
00-09 System & employment
10-19 [Primary work domain]
20-29 Career development
30-39 Professional visibility
Child/Dependent System
00-09 System
10-19 Identity & documents
20-29 School / academics
30-39 Health & medical
40-49 Activities & interests
These are suggestions, not prescriptions. The user's actual needs should drive the structure.
Johnny.Decimal Task Manager
This skill manages tasks in Johnny.Decimal systems using the jdtodo.txt
plain-text format. It reads, creates, completes, cancels, and modifies tasks
stored in todo.txt files within 00.02 Tasks/ folders. It also handles
done.txt (completed and cancelled tasks) and someday.txt (deferred items).
Before processing, read references/jdtodo-spec.md for the complete jdtodo.txt
format specification.
1. Orientation: Discover the JD Environment
Before touching any files, build a mental map of the user's JD setup.
1.1 Locate the JD Root
The JD root folder is wherever the user's systems live. Common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/- A project-specific folder the user designates
If you don't know the root, ask the user. If the user says "show my tasks" without further context, check the most common locations above. If you find exactly one, confirm it. If you find multiple or none, ask.
1.2 Identify Systems
List the top-level folders under the JD root. Each folder whose name matches
the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal,
W20 Work, C40 Citywide).
If the user has a single system (no SYS prefix), treat the entire JD root as one system.
1.3 Load Each System's JDex
For every system you'll work with, read the JDex file at:
SYS/00-09 */00 */00.00 *JDex*
The JDex is needed to validate JD codes on tasks and to display human-readable
descriptions alongside +AC.ID references. If the JDex is missing, you can
still manage tasks but cannot validate JD code references — flag this to the
user.
1.4 Locate Task Files
For each system, look for task files at:
SYS/00-09 */00 */00.02 Tasks*/todo.txt
SYS/00-09 */00 */00.02 Tasks*/done.txt
SYS/00-09 */00 */00.02 Tasks*/someday.txt
Legacy detection: If a file named 00.02 Tasks.md exists (instead of a
00.02 Tasks/ directory), this is the legacy markdown-checkbox format from the
system setup workflow. See §10 for migration guidance.
If no task files exist at all, offer to create the 00.02 Tasks/ directory
with an empty todo.txt.
2. Parse Tasks
Each line in todo.txt (and done.txt, someday.txt) is a task. Parse using
these rules from the jdtodo.txt specification.
2.1 Logical Lines
A task is one logical line. If a line ends with \ (backslash as the very last
character, no trailing whitespace), the next physical line is a continuation of
the current task's note. Gather all continuation lines before parsing.
Skip blank lines and any lines that are entirely whitespace.
2.2 Task States
Determine the task state from the line prefix:
| Prefix | State | File |
|---|---|---|
x YYYY-MM-DD | Complete | done.txt |
~ YYYY-MM-DD | Cancelled | done.txt |
(A) through (Z) | Incomplete (with priority) | todo.txt |
| Anything else | Incomplete (no priority) | todo.txt |
2.3 Priority and Dates
For incomplete tasks:
- If the line starts with
(X)where X is A–Z, extract the priority. - After priority (or at line start if no priority), check for a date in
YYYY-MM-DDformat — this is the creation date.
For complete/cancelled tasks:
- After the
xor~marker, the first date is the completion/cancellation date. - The second date (if present) is the creation date.
2.4 Contexts and Projects
Scan the task body (everything before --- if a note exists) for:
- Contexts: tokens matching
@non-whitespace(e.g.,@phone,@laptop,@waiting,@someday) - Projects: tokens matching
+non-whitespace(e.g.,+GarageSale,+N42.12.05)
JD code detection regex for project tags:
\+([A-Z]\d{2}\.)?\d{2}\.\d{2}(\+[A-Za-z0-9]+)?
This matches +AC.ID, +SYS.AC.ID, +AC.ID+SUB, and +SYS.AC.ID+SUB.
2.5 Key:Value Extensions
Extract recognized key:value pairs from the task body:
| Key | Value format | Purpose |
|---|---|---|
due | YYYY-MM-DD or someday | Hard deadline |
before | YYYY-MM-DD or someday | Soft deadline |
t | YYYY-MM-DD or someday | Threshold / visibility gate (user deferral) |
after | YYYY-MM-DD or someday | Visibility gate (external constraint) |
id | Non-whitespace, no colons | Task identifier |
dep | Non-whitespace, no colons | Blocked by another task |
sup | Non-whitespace, no colons | Subtask of another task |
rec | [+]N[d|w|m|y|b] | Recurrence interval |
h | 1 | Hidden from default views |
pri | A–Z | Preserved priority (on completed tasks) |
Preserve any unrecognized key:value pairs when modifying tasks.
2.6 Notes
If the task body contains --- (space-hyphen-hyphen-hyphen-space), everything
after the first occurrence is the note. The note may span multiple physical lines
via \ continuation. Leading whitespace on continuation lines is trimmed.
Key:value pairs in the note are freeform text — do NOT parse them as task metadata.
3. List and Filter Tasks
3.1 Default View
When the user asks to see their tasks without specific filters, show all actionable tasks. A task is actionable if ALL of these are true:
- It is incomplete (not
xor~) - It is not hidden (
h:1absent) - Its threshold date has passed or is absent (
t:date ≤ today, or not:) - Its
after:date has passed or is absent (after:date ≤ today, or noafter:) - It does not have
@somedaycontext - It does not have
due:someday - All
dep:references point to completed tasks (or the referencedid:does not exist in the active task list)
Tasks with unresolved dependencies are shown in a separate Blocked section rather than hidden entirely.
3.2 Filter by Context
When the user specifies a context (e.g., "show me @phone tasks"), show only tasks that have that context tag. Common filters:
@phone— calls to make@laptop— computer work@errands— out-of-house tasks@waiting— blocked on someone else@someday— not currently actionable@agenda— discuss at next meeting
3.3 Filter by Project or JD Code
When the user specifies a project or JD code:
+GarageSale— all tasks in that named project+N42.12.05— all tasks referencing that JD ID+N42.12— all tasks referencing any ID in that JD category
3.4 Filter by Priority
Show tasks at or above a given priority:
- "show priority A tasks" → only
(A)tasks - "show high priority" →
(A)and(B)tasks - "show all priorities" → all tasks grouped by priority
3.5 Filter by Date
- overdue: Tasks where
due:orbefore:date is before today - due today: Tasks where
due:is today - due this week: Tasks where
due:is within the next 7 days - upcoming: Tasks where
due:is within the next 14 or 30 days - no due date: Tasks with no
due:orbefore:tag
3.6 Dependency Resolution
Build the dependency graph from id:, dep:, and sup: tags:
- Index all tasks by their
id:value. - For each task with
dep:X, check ifid:Xexists and is incomplete. - If
id:Xis incomplete, the task is blocked. - If
id:Xis complete (in done.txt) or doesn't exist, the dependency is resolved.
Show blocked tasks in a separate section with the blocking task identified:
### Blocked
(B) Sort items into keep/sell/donate +GarageSale dep:garage-clean
↳ blocked by: (A) Clean out garage for sale [garage-clean]
For sup: relationships, show subtask grouping when listing by project:
### +GarageSale
(A) Clean out garage for sale id:garage-clean due:2026-05-01
├─ (B) Sort items into keep/sell/donate sup:garage-clean
├─ (B) Sweep and mop garage floor sup:garage-clean
└─ (C) Arrange sale items on tables sup:garage-clean dep:sort-items
3.7 Grouping
Default grouping is by priority. The user may request grouping by:
- System: Group tasks by JD system (for cross-system views)
- Project: Group by
+projector+AC.IDtags - Context: Group by
@contexttags - Due date: Group into overdue / today / this week / later / no date
- Priority: Group by
(A),(B),(C), etc.
3.8 Cross-System View
When no system is specified and multiple systems have task files, merge all
tasks and show system context. Prefix each task's display with its system
code if it's identifiable from +SYS.AC.ID tags or from which system's
todo.txt it came from:
## All Systems — 15 active tasks
### Priority A
[P10] (A) Submit quarterly tax estimate +N42.13.02 @laptop due:2026-04-15
[W20] (A) Respond to P0 incident follow-up +G24.21.05 @work due:2026-02-10
### Priority B
[P10] (B) Schedule dentist for Hannah +H11.25.01 @phone before:2026-03-01
3.9 JD Code Enrichment
When displaying tasks with JD code project tags, look up the code in the system's JDex and show the ID description:
(A) Submit quarterly tax estimate +N42.13.02 @laptop due:2026-04-15
↳ N42.13.02 = Tax returns & estimates
This helps the user understand the JD cross-reference without leaving the task view.
4. Add Tasks
4.1 Constructing a Task Line
Build a well-formed jdtodo.txt line from user input. The minimum requirement is a task description — everything else is optional. The line format is:
[(priority)] [creation-date] description [@contexts] [+projects] [key:values] [ --- note]
4.2 Creation Date
Always add today's date as the creation date on new tasks.
4.3 Priority
If the user specifies a priority, add it. If they don't mention priority, do not add one — unprioritized tasks are valid. Only ask about priority if the task sounds urgent or time-sensitive and the user didn't specify.
4.4 JD Code Integration
When the user mentions a JD location or the task clearly relates to a JD ID:
- Add the appropriate
+AC.IDor+SYS.AC.IDproject tag. - Validate the code against the JDex. If the code doesn't exist, warn the user and ask whether to use it anyway or choose a different ID.
- If the user describes a domain but doesn't specify a JD code (e.g., "add a task about insurance"), suggest relevant IDs from the JDex.
4.5 Contexts
If the task description implies a context, suggest it:
- Phone calls →
@phone - Computer work →
@laptop - Errands or physical locations →
@errands - Waiting on someone →
@waiting - Meeting discussion items →
@agenda
Add suggested contexts only if the user confirms or if the mapping is obvious
(e.g., "call the dentist" clearly gets @phone).
4.6 Dates
When the user mentions a deadline or timing:
- "by Friday" / "due next week" → convert to
due:YYYY-MM-DD - "before the party" → ask for a specific date, then use
before:YYYY-MM-DD - "not until June" / "after surgery" → convert to
after:YYYY-MM-DDort:YYYY-MM-DD - "someday" / "eventually" → use
due:somedayor@someday
Use due: for hard deadlines, before: for soft targets, t: for user
deferrals, and after: for external constraints. When in doubt, ask which
semantic the user intends.
4.7 Relationships
If the task is part of a project that has existing tasks with id: tags:
- Show the existing task graph for that project.
- Offer to set
sup:(subtask) ordep:(blocked by) links. - If the new task should be identifiable by other tasks, suggest an
id:— keep it short and descriptive (e.g.,id:post-signs).
4.8 Notes
If the user provides additional context beyond the task description, add it as
a note after ---. For multi-line notes, use \ continuation:
(B) 2026-02-09 Schedule vet appointment @phone --- Last checkup was October. \
Needs rabies booster.
4.9 Recurrence
If the task repeats:
- "every 3 days" →
rec:3d - "weekly" →
rec:1w - "monthly on the 1st" →
rec:+1m(strict, anchored to date) - "every 2 weeks" →
rec:2w - "every business day" →
rec:1b
Use strict mode (+ prefix) when the task is calendar-anchored (rent, reports).
Use non-strict when the interval from last completion matters (watering plants).
4.10 Which File
- New tasks go in
todo.txtby default. - Tasks with
@somedayordue:somedaymay optionally go insomeday.txtif the user has a separate someday file. Ask the user their preference if both options are available.
4.11 Confirm Before Writing
Before adding the task, show the user the complete formatted line:
Adding to P10 todo.txt:
(B) 2026-02-09 Schedule vet appointment for Max +N42.25.01 @phone before:2026-03-01 --- Last checkup was October. Needs rabies booster.
Proceed after confirmation, or adjust based on feedback.
5. Complete and Cancel Tasks
5.1 Identifying the Task
When the user says "complete the insurance task" or "mark that done," identify the target task:
- Search active tasks for keyword matches in the description.
- If the user references a JD code,
id:, project, or context, use those to narrow the search. - If exactly one task matches, confirm it with the user.
- If multiple tasks match, present the candidates and ask which one(s).
- If no tasks match, say so and offer to list tasks for the user to choose.
5.2 Completing a Task
To mark a task complete:
- Strip the
(X)priority from the line start (if present). - Prepend
x YYYY-MM-DDusing today's date as the completion date. - If the task had a priority, add
pri:Xto the end of the task body (before any---note). - Preserve all other content: description, contexts, projects, key:value pairs, and notes.
Before completion:
(A) 2026-02-01 Call Goodwill +GarageSale @phone due:2026-02-15
After completion:
x 2026-02-09 2026-02-01 Call Goodwill +GarageSale @phone due:2026-02-15 pri:A
5.3 Cancelling a Task
To cancel a task:
- Strip the
(X)priority (if present). - Prepend
~ YYYY-MM-DDusing today's date as the cancellation date. - If the task had a priority, add
pri:X. - Ask the user for a cancellation reason and append it as a note.
Before cancellation:
(B) 2026-02-01 Order extra tables +GarageSale
After cancellation:
~ 2026-02-09 2026-02-01 Order extra tables +GarageSale pri:B --- Lauren has enough tables.
5.4 Handle Recurrence
When completing a task that has a rec: tag:
- Complete the original task as described in §5.2.
- Create a new incomplete task with the same description, projects, contexts,
key:value pairs (except
pri:— restore the original priority), and notes. - Shift date fields forward by the recurrence interval:
Non-strict (no + prefix, e.g., rec:3d): Calculate from today's date
(the completion date).
Strict (+ prefix, e.g., rec:+1m): Calculate from the original due:
date.
- Shift all date fields:
due:,t:,before:,after:. Preserve the gap betweent:anddue:(ift:was 15 days beforedue:, the newt:should be 15 days before the newdue:). - Set the creation date on the new task to today (the completion date).
Example — non-strict:
# Original (completed today, Feb 12):
x 2026-02-12 2026-02-09 Water all houseplants @home rec:3d due:2026-02-09 → done.txt
# New task:
(B) 2026-02-12 Water all houseplants @home rec:3d due:2026-02-15 → todo.txt
Example — strict:
# Original (completed today, Feb 1):
x 2026-02-01 2026-01-01 Pay rent rec:+1m due:2026-02-01 → done.txt
# New task (based on original due date, not completion date):
2026-02-01 Pay rent rec:+1m due:2026-03-01 → todo.txt
5.5 Move to done.txt
After completing or cancelling a task:
- Remove the task line (and any
\continuation lines) fromtodo.txt. - Append the completed/cancelled line to
done.txt. - If
done.txtdoes not exist, create it. - If the task was recurring, the new occurrence stays in
todo.txt.
5.6 Batch Completion
When completing multiple tasks at once, present a confirmation table:
Complete these tasks?
| # | Task | Status |
|---|------|--------|
| 1 | Call Goodwill +GarageSale @phone | → done.txt |
| 2 | Water houseplants @home rec:3d | → done.txt + new occurrence |
| 3 | File insurance claim +N42.11.03 | → done.txt |
Proceed with all 3? [y/n/select specific]
6. Modify Tasks
6.1 Change Priority
Update or add (X) at the start of the task line. If the task already has a
priority, replace it. If it has no priority, insert before the creation date
(or before the description if no creation date).
6.2 Add or Change Dates
Add or modify due:, before:, t:, after: tags. If the tag already
exists, replace its value. If new, append to the task body (before ---).
6.3 Add Contexts or Projects
Append @context or +project tags to the task body. Check for duplicates
before adding.
6.4 Add or Update Notes
- If the task has no note, add
---followed by the note text. - If the task already has a note, append to it (add a
\continuation if needed for multiline).
6.5 Set Up Relationships
Add id:, dep:, or sup: tags to the task body:
- When adding
id:, verify the identifier is unique within the file. - When adding
dep:, verify the referencedid:exists. - When adding
sup:, verify the referencedid:exists.
6.6 Move to Someday
To defer a task indefinitely:
- Add
@somedayor changedue:todue:someday. - If the user has a separate
someday.txt, offer to move the task there. - Remove
t:andafter:dates if present (they're superseded by someday status).
6.7 Reactivate from Someday
To bring a task back from someday:
- Remove
@somedaycontext anddue:someday(if present). - If the task is in
someday.txt, move it totodo.txt. - Ask the user for a new due date or leave undated.
7. Review Mode
Review mode is a guided walkthrough for periodic task maintenance — typically weekly.
7.1 Someday Review
Present each task in someday.txt (or tasks with @someday/due:someday in
todo.txt):
For each task, offer:
- Keep: Leave as someday.
- Activate: Move to
todo.txt, set a due date, remove@someday. - Cancel: Mark cancelled with reason, move to
done.txt.
7.2 Deferred Tasks
Show tasks whose t: or after: date has passed — these are now actionable
but may have been overlooked:
These tasks are now actionable:
(B) Renew car registration +N42.12.01 t:2026-06-01 due:2026-06-30
↳ Threshold date passed (was deferred until Jun 1)
Also show tasks with t: or after: dates in the next 7 days — coming up
soon.
7.3 Stale Tasks
Identify incomplete tasks that may be stale:
- Created more than 30 days ago with no due date and no recent modification
- No priority set
- Not part of an active project
For each stale task, offer: keep as-is, set a due date, move to someday, or cancel.
7.4 Dependency Check
Show tasks whose blocking dependencies have been resolved since the last review — these are newly actionable:
Newly unblocked:
(B) Post signs around neighborhood +GarageSale dep:plan-sale
↳ plan-sale was completed on 2026-02-05
7.5 Overdue Summary
Present all tasks past their due: date, sorted by how overdue:
Overdue tasks:
(A) Respond to P0 follow-up +G24.21.05 due:2026-02-10 [9 days overdue]
(B) Review tuition bill +V06.31.02 due:2026-02-28 [past due]
For each, offer: complete (if done), reschedule (set new due date), or cancel.
8. JD Integration
8.1 Cross-Referencing with JDex
When a task uses +AC.ID or +SYS.AC.ID project tags:
- Look up the code in the relevant system's JDex.
- If found, display the JDex description alongside the task when showing task lists.
- If not found, warn the user: "JD code +N42.12.05 is not in the JDex. Create the ID, or use a different code?"
8.2 Context from JD System
When displaying tasks, enrich JD code references:
(A) Clean out garage for sale +N42.12.05 due:2026-05-01
↳ N42.12.05 = Garage maintenance (in P10 Personal)
This is informational — it helps the user remember what the JD code refers to without switching context.
8.3 Task Extraction Compatibility
The inbox processor skill (§4 of jd-inbox-processor) extracts tasks in
markdown-checkbox format and appends them to 00.02 Tasks. When both skills
are in use:
- If the task file is
todo.txt(jdtodo.txt format), extracted tasks should be written in jdtodo.txt format instead of markdown checkboxes. - The jdtodo.txt format is preferred when a
todo.txtfile exists. - If only
00.02 Tasks.mdexists (legacy format), the inbox processor's format is compatible until migration (see §10).
8.4 Multi-System Tasks
A single todo.txt may reference multiple systems via +SYS.AC.ID tags.
Alternatively, each system may have its own todo.txt. Handle both approaches:
- Single file: All tasks in one
todo.txt, system identified by project tags. - Per-system files: Separate
todo.txtper system, merged for cross-system views.
When displaying cross-system views, avoid duplicate id: confusion by
mentally namespacing — if two systems both have an id:plan, show the system
context to disambiguate.
9. Interaction Principles
9.1 When to Ask vs. When to Act
- Act without asking: Listing tasks, showing filtered views, resolving dependency graphs, enriching JD code references. These are read-only and safe.
- Confirm before acting: Completing tasks, cancelling tasks, moving tasks between files (todo.txt ↔ done.txt ↔ someday.txt), modifying tasks the user has specifically identified. Present the change and get a "yes."
- Always ask: Deleting task lines (prefer moving to done.txt — never truly delete without explicit user confirmation), modifying tasks that the user hasn't specifically identified, creating task files or directories.
9.2 Task Identification
When the user refers to a task by description ("the insurance one," "that garage sale task"), use these signals to identify it:
- Keywords in the task description
- JD codes or project tags mentioned by the user
- Context tags (
@phone,@laptop) - Priority level
- Recency — if the user just added or discussed a task, it's likely the one they mean
If ambiguous, present the top 2–3 candidates:
I found 2 tasks matching "insurance":
- (A) Call insurance company about claim +N42.11.03 @phone
- (C) Research new homeowner's insurance quotes +N42.11.03 @laptop
Which one?
9.3 Format Preservation
When modifying todo.txt:
- Preserve all existing formatting, whitespace, and ordering.
- Append new tasks at the end of the file.
- Do not re-sort the file unless the user explicitly asks.
- When removing a completed task, remove the exact line(s) including any
\continuation lines. - Preserve blank lines and any comment-like lines (though jdtodo.txt doesn't formally define comments, users may have them).
10. Error Handling
10.1 Task File Missing
If todo.txt doesn't exist at the expected location:
- Check if a
00.02 Tasks/directory exists. If so, createtodo.txtin it. - If only
00.02 Tasks.mdexists (flat file), see §10.2. - If nothing exists, offer to create the
00.02 Tasks/directory with an emptytodo.txt.
10.2 Legacy Format Migration
If 00.02 Tasks.md exists with markdown-checkbox tasks:
- [ ] Call the insurance company
- [x] File the tax return
- [ ] Schedule dentist appointment
Offer to migrate to jdtodo.txt format:
- Convert
- [ ] description→YYYY-MM-DD description(using today's date as creation date, since the original has none). - Convert
- [x] description→x YYYY-MM-DD description(using today as completion date). - Extract any JD references, contexts, or dates from the markdown text and convert to proper tags.
- Write the converted tasks to
00.02 Tasks/todo.txt(completed todone.txt). - Rename
00.02 Tasks.mdto00.02 Tasks.md.bak(do not delete).
Always confirm the migration plan with the user before executing.
10.3 Invalid JD Codes
If a task references a +AC.ID that isn't in the JDex:
- When listing: Show the task but flag the invalid reference.
- When adding: Warn before writing and offer alternatives.
- Do not block operations on tasks with invalid codes — they may be intentional placeholders.
10.4 Circular Dependencies
If dep: chains form a cycle (A depends on B, B depends on A):
- Warn the user about the cycle.
- Show which tasks are involved.
- Suggest removing one of the dependencies to break the cycle.
- Do not modify anything automatically.
10.5 Duplicate Task IDs
If multiple tasks in the same file have the same id: value:
- Warn the user when the duplicate is detected.
- Show both tasks with the duplicate ID.
- Suggest renaming one of them.
10.6 File Write Errors
If writing to a file fails (permissions, disk full, etc.):
- Report the error clearly.
- Do not attempt to modify the original file again.
- Show the user the change that was attempted so they can apply it manually.
11. Post-Action Summary
After any write operation (add, complete, cancel, modify), present a summary:
Task update complete.
P10 Personal: 12 active, 3 overdue
Completed: 2 tasks (moved to done.txt)
Recurring: 1 new occurrence generated
Added: 1 new task
W20 Work: 5 active, 1 overdue
Completed: 1 task (moved to done.txt)
For review sessions, provide a more detailed summary:
Weekly review complete.
Someday: 3 reviewed → 1 activated, 1 cancelled, 1 kept
Deferred: 2 tasks now actionable
Stale: 1 task moved to someday
Overdue: 3 tasks rescheduled
Newly unblocked: 1 task
Quick Reference: Task File Locations
SYS/00-09 System/00 System management/00.02 Tasks/
├── todo.txt # Active and deferred tasks
├── done.txt # Completed and cancelled tasks
└── someday.txt # @someday items (optional)
Quick Reference: Task States
| State | Line prefix | Stored in |
|---|---|---|
| Incomplete | (none, or (A)) | todo.txt |
| Complete | x YYYY-MM-DD | done.txt |
| Cancelled | ~ YYYY-MM-DD | done.txt |
| Someday | @someday or due:someday | someday.txt (optional) or todo.txt |
| Hidden | h:1 | todo.txt (excluded from views) |
Quick Reference: Date Tags
| Tag | Meaning | Visibility effect |
|---|---|---|
due:YYYY-MM-DD | Hard deadline | Overdue highlighting |
before:YYYY-MM-DD | Soft deadline | Same as due: for display |
t:YYYY-MM-DD | Don't show until | Hidden before date |
after:YYYY-MM-DD | Can't start until | Hidden before date |
due:someday | Indefinite | Hidden from default views |
Commands 6
Audit JDex
Compare a system's JDex against its actual folder structure, flagging orphaned entries, undocumented folders, name mismatches, and +SUB index issues.
Arguments
$ARGUMENTS may contain a system code (e.g., P10) to audit a specific
system. If no argument is provided, list all available systems and ask which
to audit.
Workflow
- Load the target system's JDex.
- Snapshot the filesystem to depth 3.
- Compare JDex entries against folders:
- Orphaned JDex entries (in JDex, no folder)
- Undocumented folders (folder exists, not in JDex)
- Name mismatches between JDex and folder names
- Check +SUB index files against +SUB folders.
- Report findings in a structured table.
- Offer fixes: Add missing JDex entries, update +SUB indexes, or flag items that need user decisions.
Safe Fixes
- Adding undocumented folders to the JDex
- Updating +SUB index files with missing entries
Requires User Decision
- Orphaned JDex entries (create folder or remove entry?)
- Name mismatches (which name is correct?)
- Deleting or renaming any folder
Examples
/jd:jdex-audit
/jd:jdex-audit P10
/jd:jdex-audit F50
Manage Tasks
View, add, complete, cancel, and modify tasks in Johnny.Decimal 00.02 Tasks/
folders using the jdtodo.txt format. Handles todo.txt, done.txt, and
someday.txt files.
Arguments
$ARGUMENTS may contain:
- A system code (e.g.,
P10) to target a specific system's tasks. - An action keyword:
add,complete,cancel,list,modify,review. - Filter criteria: priority (
A), context (@phone), project (+GarageSale), JD code (+N42.12.05), or date range (overdue,due:this-week). - No arguments to list all actionable tasks across all systems.
Workflow
- Discover the JD root and available systems.
- Locate task files at
00.02 Tasks/in each system (todo.txt,done.txt,someday.txt). - Parse todo.txt files using jdtodo.txt format rules.
- Execute the requested action (list, add, complete, cancel, modify, review).
- Handle recurrence: When completing a recurring task, generate the next occurrence and keep the original in done.txt.
- Archive: Move completed and cancelled tasks to done.txt.
- Resolve dependencies: Show blocked vs. actionable tasks.
- Summarize changes made.
Actions
- list (default): Show actionable tasks with filtering and grouping.
- add: Create a new task with priority, dates, contexts, projects, and JD codes.
- complete: Mark one or more tasks as done, handle recurrence, move to done.txt.
- cancel: Mark tasks as cancelled with reason, move to done.txt.
- modify: Change priority, add dates, add notes, update contexts or projects.
- review: Show someday items and deferred tasks for weekly review.
Examples
/jd:manage-tasks
/jd:manage-tasks P10
/jd:manage-tasks P10 add
/jd:manage-tasks list @phone
/jd:manage-tasks list overdue
/jd:manage-tasks review
Next Action Dashboard
Generate a prioritized report of everything requiring attention across Johnny.Decimal systems — combining active tasks, unprocessed inbox items, and items needing review into a single view ordered from most urgent to least urgent.
Arguments
$ARGUMENTS may contain:
- A system code (e.g.,
P10) to limit the report to a specific system. - A context filter (
@phone,@laptop,@errands). - A project filter (
+GarageSale,+N42.12.05). - A timeframe filter (
this-week). - No arguments to show all systems with all actionable items.
Workflow
- Discover the JD root and available systems.
- Scan data sources per system:
00.02 Tasks/todo.txt— active tasks00.01 Inbox/— unprocessed item counts00.04 Needs review/— items requiring decisions00.02 Tasks/someday.txt— deferred item count
- Parse tasks using jdtodo.txt format and filter for actionable items.
- Categorize into priority buckets: overdue, due today, inbox, needs review, high priority, due this week, other actionable, coming up.
- Generate a markdown report with one section per non-empty bucket.
- Summarize with counts, blocked/waiting stats, and recommended focus.
Priority Order (Highest to Lowest)
- Overdue tasks
- Due today
- Inbox items (unknown urgency)
- Needs review items
- High priority
(A)tasks - Due this week
- Other actionable tasks
- Coming up (threshold dates approaching within 14 days)
Examples
/jd:next-action
/jd:next-action P10
/jd:next-action @phone
/jd:next-action +GarageSale
/jd:next-action this-week
See Also
/jd:manage-tasks— View, add, complete, and modify tasks/jd:process-inbox— Classify and file inbox items
Process Johnny.Decimal Inbox
Process items in one or more Johnny.Decimal 00.01 Inbox folders. Each item
is read, classified against the JDex and folder structure, and moved to the
correct ID location.
Arguments
$ARGUMENTS may contain a system code (e.g., P10) to process a specific
system's inbox. If no argument is provided, discover all systems and their
inboxes, then ask which to process.
Workflow
- Discover the JD root and available systems.
- Load the target system's JDex and folder structure.
- List inbox contents and report item count, types, and date range.
- Classify each item using the JDex as the primary reference.
- File items to their destination ID folders with date-prefix naming.
- Extract tasks from items that contain action items.
- Log every action to the processing log at
00.03 Processing log.md. - Summarize what was processed, filed, and flagged.
Classification Confidence
- High confidence: File without asking.
- Medium confidence: Recommend a destination and ask the user to confirm.
- Low confidence: Present 2–3 candidate locations and ask the user to choose.
Batch Mode
For inboxes with many items, present a table of proposed filings and let the user approve, modify, or flag specific items before executing.
Examples
/jd:process-inbox
/jd:process-inbox P10
/jd:process-inbox W20
Set Up a Johnny.Decimal System
Create a new Johnny.Decimal system from scratch — folders, standard zeros, and initial JDex.
Arguments
No required arguments. The command will walk the user through an interactive setup process.
Workflow
- Ask whether this is a single-system or multi-system setup.
- Gather system identity: code (if multi-system), name, and root location.
- Define areas: Walk through area definitions (max 10 including 00-09).
- Define categories: For each area, define categories (max 10 per area).
- Define initial IDs: Optionally pre-create ID folders within categories.
- Create structure: Build all folders on disk.
- Generate JDex: Write the complete index at
00.00 JDex.md. - Initialize files: Create
00.02 Tasks.mdand00.03 Processing log.md. - Verify: Display the complete folder tree for user review.
Templates
Offer starting templates for common system types:
- Personal life: Home, family, money, health, projects, travel, hobbies
- Work: System/employment, primary work domain, career, visibility
- Child/dependent: Identity, school, health, activities
Examples
/jd:setup-system
Manage +SUB Index
Scan a +SUB category, update its index file, and optionally create new +SUB entries with the next sequential number.
Arguments
$ARGUMENTS may contain:
- A system code (e.g.,
P10) and category number (e.g.,51) to target a specific +SUB category. - Just a system code to list all +SUB categories in that system.
- No arguments to discover all +SUB categories across all systems.
Workflow
- Locate the target +SUB category and its index file.
- Scan existing +SUB folders (matching
AC.ID+NNNNorAC.ID+CODE). - Compare folder entries against the index file.
- Update the index with any missing entries.
- Report the current state: total entries, active/archived counts, next available number.
Creating New Entries
When the user wants to add a new +SUB entry:
- Determine the next identifier (sequential number or user-provided code).
- Create the +SUB folder.
- Update the index file.
- Update the JDex.
Examples
/jd:sub-index
/jd:sub-index P10
/jd:sub-index P10 51
Sponsors
Details
- Marketplace
- ngerakines/jd
- Source
- jd
- Category
- Community
