WORK-143
ID:WORK-143Status:done

Rename plan directories to plural form

Change the plan package's directory convention from singular to plural: spec/ to specs/, decision/ to decisions/, milestone/ to milestones/. Keep work/ unchanged (collective noun).

Priority:mediumComplexity:simpleSource:SPEC-039
claude/file-naming-convention-LJdwR View source

Criteria completion

No incremental history — criteria tracking started on Apr 21.

Relationships

Implements 1
Related 1
Branches 2
claude/file-naming-convention-LJdwR current done
main donechangeset-release/main done
History 2
  1. bbbb94c
    Created (done)by bjornolofandersson
  2. f2b3512
    Content editedby Claude
    Add {ID}-{slug}.md filename convention + migrate filenames subcommand

Acceptance Criteria

  • plan init creates specs/, work/, decisions/, milestones/ directories
  • plan create writes files to the correct plural directories
  • Status filter pages and type index pages use the new directory names
  • TYPE_DIRS mapping in create.ts updated
  • STATUS_PAGES in templates.ts updated with new typeDir values
  • TYPE_TITLES in templates.ts updated
  • init.ts directory list updated
  • plan/INSTRUCTIONS.md (or plan/CLAUDE.md until WORK-142 lands) documents the new structure
  • Root CLAUDE.md plan section updated to reflect new directory names
  • Our own plan/ directory renamed manually (spec/ to specs/, decision/ to decisions/, milestone/ to milestones/)
  • All internal links in existing plan content updated (e.g., index.md links to subdirectories)
  • Scanner still finds entities correctly after rename (it scans recursively, but verify)

Approach

This is a straightforward find-and-replace across a small number of files. The scanner (scanner.ts) scans recursively from the plan root so it doesn't care about directory names — no changes needed there.

Files to modify in runes/plan/src/

  • commands/init.ts — const dirs = ['work', 'specs', 'decisions', 'milestones'] and example file paths
  • commands/create.ts — TYPE_DIRS mapping: spec: 'specs', decision: 'decisions', milestone: 'milestones'
  • commands/templates.ts — STATUS_PAGES[].typeDir entries and TYPE_TITLES keys

Files to update in docs

  • CLAUDE.md (root) — directory layout section
  • plan/CLAUDE.md — directory layout section (or plan/INSTRUCTIONS.md if WORK-142 lands first)
  • site/content/runes/plan/index.md — directory structure references
  • site/content/runes/plan/cli.md — directory paths in command examples
  • site/content/runes/plan/workflow.md — directory layout references

Manual migration of our own content

Rename directories and update any hardcoded paths in index/status pages:

cd plan
git mv spec specs
git mv decision decisions
git mv milestone milestones

Then update links in plan/index.md and any status filter pages that reference sibling directories.

Dependencies

  • Ideally lands after WORK-142 so the docs update targets INSTRUCTIONS.md rather than CLAUDE.md, but not strictly blocking

References

  • SPEC-039 — parent spec

Resolution

Completed: 2026-04-14

Branch: claude/plan-package-review-Z4sJE

What was done

  • Updated init.ts: directory list, example subDirs, index.md links, INSTRUCTIONS_CONTENT
  • Updated create.ts: TYPE_DIRS mapping (spec→specs, decision→decisions, milestone→milestones)
  • Updated templates.ts: STATUS_PAGES typeDir values and TYPE_TITLES keys
  • Updated init.test.ts: all directory path assertions
  • Renamed our own plan directories: spec/→specs/, decision/→decisions/, milestone/→milestones/
  • Updated site docs: index.md, cli.md, workflow.md directory references
  • Updated root CLAUDE.md and plan/INSTRUCTIONS.md
  • Scanner confirmed working (scans recursively, directory names don't matter)
  • 51 tests passing (init + create)

Notes

  • work/ stays singular — collective noun, "works" is awkward
  • No migration command needed since we're the only users