7.1 KiB

Raw Blame History

WDS Agent File Naming Conventions

For: All WDS Agents (Freya, Saga, Idunn)
Purpose: Consistent file naming across all WDS projects
Version: 1.0

🎯 Core Principle

Use descriptive, specific file names - NOT generic names like "README"

❌ DON'T Use Generic Names

Never Create:

❌ README.md (too generic, confusing when multiple exist)
❌ INSTRUCTIONS.md (instructions for what?)
❌ GUIDE.md (guide for what?)
❌ NOTES.md (notes about what?)
❌ INFO.md (info about what?)

Problem: When there are 5 README files, which one do you read?

✅ DO Use Specific Names

Always Create:

✅ AGENTIC-DEVELOPMENT-GUIDE.md (specific topic)
✅ FREYA-WORKFLOW-INSTRUCTIONS.md (specific agent + purpose)
✅ PROTOTYPE-ROADMAP.md (specific purpose)
✅ PROJECT-ANALYSIS-ROUTER.md (specific function)
✅ COMPONENT-NAMING-CONVENTIONS.md (specific topic)

Benefit: Clear, self-documenting, no confusion

📋 Naming Patterns

Pattern 1: [TOPIC]-GUIDE.md

When: Overview/introduction to a topic
Examples:

AGENTIC-DEVELOPMENT-GUIDE.md
DESIGN-SYSTEM-GUIDE.md
TESTING-GUIDE.md

Pattern 2: [AGENT]-[PURPOSE]-INSTRUCTIONS.md

When: Step-by-step instructions for specific agent
Examples:

FREYA-WORKFLOW-INSTRUCTIONS.md
SAGA-ANALYSIS-INSTRUCTIONS.md
IDUNN-HANDOFF-INSTRUCTIONS.md

Pattern 3: [PURPOSE]-TEMPLATE.[ext]

When: Reusable template files
Examples:

work-file-template.yaml
story-file-template.md
page-template.html
demo-data-template.json

Pattern 4: [SPECIFIC-TOPIC].md

When: Documentation for specific feature/concept
Examples:

PROTOTYPE-ROADMAP.md
SYSTEM-GUIDE.md
FILE-INDEX.md
PROTOTYPE-ANALYSIS.md

Pattern 5: [function]-[purpose].md

When: Instruction files for specific workflows
Examples:

project-analysis-router.md
outline-based-analysis.md
strategy-work.md
design-work.md

🗂️ Folder Organization

Documentation Folders Should Contain:

workflow-folder/
├── [TOPIC]-GUIDE.md                 ← Main entry point
├── [AGENT]-INSTRUCTIONS.md          ← Agent-specific steps
├── [SPECIFIC-TOPIC].md              ← Supporting docs
├── templates/
│   ├── [name]-template.[ext]
│   └── ...
└── examples/
    └── ...

NOT:

workflow-folder/
├── README.md                        ← ❌ Too generic
├── README-2.md                      ← ❌ Even worse!
├── INSTRUCTIONS.md                  ← ❌ Instructions for what?
└── GUIDE.md                         ← ❌ Guide for what?

💡 Benefits of Specific Naming

Benefit	Description
Self-documenting	File name tells you what it contains
No confusion	Can't mistake one file for another
Easy search	Find exact file you need
Better IDE	File tabs show meaningful names
Team clarity	Everyone knows what's what
Future-proof	Scales to 100+ files without confusion

🎯 Examples in WDS

Good (Current WDS Structure)

project-analysis/
├── instructions.md                  ← Entry point (clear function)
├── project-analysis-router.md       ← Router (specific purpose)
├── SYSTEM-GUIDE.md                  ← System overview (specific)
├── analysis-types/
│   ├── outline-based-analysis.md
│   ├── folder-based-analysis.md
│   └── empty-project-response.md
└── work-types/
    ├── strategy-work.md
    └── design-work.md

Bad (Old Pattern - Don't Do This)

project-analysis/
├── README.md                        ← ❌ Which readme?
├── instructions.md
├── GUIDE.md                         ← ❌ Guide for what?
├── analysis-types/
│   ├── README.md                    ← ❌ Another readme!
│   └── instructions.md              ← ❌ Confusing
└── work-types/
    └── README.md                    ← ❌ Yet another readme!

🚀 Action Items for Agents

When Creating New Documentation

Before creating file, ask:

What is the specific purpose of this file?
Is there already a file with this name nearby?
Can I make the name more descriptive?

Then name it: [SPECIFIC-TOPIC]-[TYPE].md

When You See Generic Names

If you encounter:

README.md without clear context
Multiple README.md files in related folders
INSTRUCTIONS.md without specificity

Recommend renaming to more specific names and document the change.

📝 File Type Suffixes

Use these suffixes for clarity:

-GUIDE.md - Comprehensive overview/introduction
-INSTRUCTIONS.md - Step-by-step how-to
-TEMPLATE.[ext] - Reusable template
-ANALYSIS.md - Analysis/research document
-REFERENCE.md - Quick reference/cheat sheet
-INDEX.md - Index/directory of files
-ROADMAP.md - Status/plan tracking

Examples:

AGENTIC-DEVELOPMENT-GUIDE.md
FREYA-WORKFLOW-INSTRUCTIONS.md
page-template.html
PROTOTYPE-ANALYSIS.md
TAILWIND-REFERENCE.md
FILE-INDEX.md
PROTOTYPE-ROADMAP.md

✅ Checklist: Good File Name?

Is it specific (not generic)?
Does it describe the content?
Is it unique in its folder?
Would a new team member understand it?
Does it include topic + type?

If all YES → Good name!
If any NO → Make more specific!

🎓 Examples

Generic → Specific

❌ Generic	✅ Specific
`README.md`	`AGENTIC-DEVELOPMENT-GUIDE.md`
`INSTRUCTIONS.md`	`FREYA-WORKFLOW-INSTRUCTIONS.md`
`GUIDE.md`	`DESIGN-SYSTEM-GUIDE.md`
`template.yaml`	`work-file-template.yaml`
`example.json`	`demo-data-template.json`

📊 Impact

Before (Generic Naming):

project/
├── README.md                        ← Which one to read?
├── folder1/
│   └── README.md                    ← Too many READMEs!
├── folder2/
│   ├── README.md                    ← Confusing!
│   └── INSTRUCTIONS.md              ← Instructions for what?
└── folder3/
    └── README.md                    ← Stop!

After (Specific Naming):

project/
├── PROJECT-OVERVIEW-GUIDE.md        ← Clear!
├── folder1/
│   └── FEATURE-X-GUIDE.md           ← Specific!
├── folder2/
│   ├── AGENT-Y-INSTRUCTIONS.md      ← Clear purpose!
│   └── WORKFLOW-Z-INSTRUCTIONS.md   ← Specific!
└── folder3/
    └── COMPONENT-W-GUIDE.md         ← Self-documenting!

🎯 Apply This Rule Everywhere

WDS Projects:

✅ Use specific names
✅ Include topic in name
✅ Include type suffix
✅ Make self-documenting

Agent Behavior:

✅ Never create generic README.md
✅ Always use specific names
✅ Recommend renaming when you see generic names
✅ Update references when renaming

Consistency creates clarity. Specific names eliminate confusion. 📚

7.1 KiB Raw Blame History