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
changeset-release/main View source

Criteria completion

No incremental history — criteria tracking started on Apr 19.

Relationships

Implements 1
Related 1
Branches 2
changeset-release/main current done
main doneclaude/file-naming-convention-LJdwR done
History 4
  1. f2b3512
    Content editedby Claude
    Add {ID}-{slug}.md filename convention + migrate filenames subcommand
  2. 9d26424
    Content editedby Claude
    Mark WORK-142 and WORK-143 as done with resolution summaries
  3. e386005
    Content editedby Claude
    Add site documentation to work item acceptance criteria
  4. 2d6c332
    Created (done)by Claude
    Add work items for plan package improvements, defer import

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