Skip to content

PRD: File Naming Convention Change

Project: ai-plans Date: 2026-02-08 Status: draft

Context

Current file structure uses uppercase filenames: project/task/PRD.md, project/task/TASKS.md, project/task/NOTES.md. We want to change to lowercase with prefixes: project/task/prd-task.md, project/task/tasks-task.md, project/task/notes-task.md.

Goals

  • Use consistent lowercase naming with prefixes
  • Make filenames more descriptive (include task name)
  • Maintain nested folder structure
  • Improve file organization and clarity

Requirements

Functional

  • Update publish_prd to create project/task/prd-task.md instead of project/task/PRD.md
  • Update publish_tasks to create project/task/tasks-task.md instead of project/task/TASKS.md
  • Update publish_notes to create project/task/notes-task.md instead of project/task/NOTES.md
  • Update update_task_status to work with new file paths
  • Update list_plans to detect new filenames
  • Update update-index.ts to generate correct links
  • Migrate existing demo plans to new structure

Non-functional

  • Maintain backward compatibility during migration
  • Update all tests to use new structure
  • Update documentation and examples

Technical Approach

  1. File Path Changes:
  2. Old: docs/project/task/PRD.md

  3. New: docs/project/task/prd-task.md

  4. URL Changes:

  5. Old: http://localhost:8100/project/task/PRD/

  6. New: http://localhost:8100/project/task/prd-task/

  7. Implementation Steps:

  8. Update filename generation in all tool files
  9. Keep folder structure unchanged (project/task/)
  10. Update list_plans to detect new filenames (check for prd-*.md pattern)
  11. Update update-index.ts link generation
  12. Test with new plan creation

  13. Migrate existing plans

  14. MkDocs Considerations:

  15. MkDocs will automatically handle new filenames
  16. Folder structure remains the same
  17. No changes needed to mkdocs.yml

Constraints and Risks

  • Breaking change for existing plans
  • Need to migrate or recreate existing demo plan
  • URLs will change (but we're still in development)
  • Tests need to be updated

Open Questions

  • Should we add migration script or just recreate existing plans?
  • Any edge cases with special characters in task names?