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
main View source

Criteria completion

Criteria completion: 12 of 12 (100%) checked; history from Apr 14 to Apr 140%25%50%75%100%Apr 14Apr 14

Relationships

Implements 1
Related 1
Branches 2
main current done
claude/file-naming-convention-LJdwR donechangeset-release/main done
History 3
  1. e900a90
    Created (done)by bjornolofandersson
  2. 9d26424
    • ☑ `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)
    by Claude
  3. 2d6c332
    Created (ready)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