7.9 KiB

Raw Blame History

Instruction File Guidelines

Purpose: Universal guidelines for creating and organizing instruction files across all WDS agents and workflows

Applies to: All agents (Saga, Freya, Idunn) and all modules (WDS, BMM, BMGD)

📏 File Size Guidelines

Files That SHOULD Be Split (Sequential Instructions)

Types:

Agent workflow files (step-by-step instructions)
Implementation guides (sequential tasks)
Process documentation (phase-by-phase)
Task instructions (do A, then B, then C)

Size Limits:

Ideal: 60-150 lines
Maximum: 180 lines before splitting

Why?

Agents read these sequentially, top-to-bottom
Large files increase chance of skipping steps
Harder to navigate and maintain
Cognitive overload for both agents and humans

When to split:

❌ Over 150 lines AND sequential
❌ Multiple distinct phases in one file
❌ File tries to do more than one job
❌ Agent must read entire file to proceed

Files That CAN Be Long (Reference/Specification)

Types:

Page specifications (comprehensive user requirements)
PRDs (product requirement documents)
Design system documentation (component library reference)
Technical architecture docs (system design)
Analysis/case studies (research, examples)
Dialog scripts (conversation patterns with examples)

Size Limits:

No strict limit - can be 300-600+ lines
Use judgment based on usability

Why?

These are human-readable reference materials
Get broken into smaller work items (stories, tasks) later
Need comprehensive detail in one place
Not read sequentially by agents (they reference specific sections)

Examples:

3.1-Dog-Calendar-Page-Spec.md (600+ lines OK)
    ↓ Broken into work files
work/3.1-Dog-Calendar-Work.yaml (planning doc)
    ↓ Broken into stories
stories/3.1.1-header.md (80 lines)
stories/3.1.2-week-overview.md (95 lines)
    ↓ Agent implements one story at a time

🗂️ File Organization Patterns

Pattern 1: Router + Micro-Steps (Best for workflows)

Structure:

workflow-name/
├── WORKFLOW-NAME.md (overview + router, 50-100 lines)
└── phases/
    ├── 1-phase-name.md (60-120 lines)
    ├── 2-phase-name.md (60-120 lines)
    └── 3-phase-name.md (60-120 lines)

Example:

project-analysis/
├── project-analysis-router.md (routes to correct analysis type)
└── analysis-types/
    ├── outline-based-analysis.md
    ├── folder-based-analysis.md
    └── empty-project-response.md

When to use:

Multi-phase workflows
Sequential processes
Agent needs to follow steps in order

Pattern 2: Spec + Stories (Best for implementation)

Structure:

feature-or-page/
├── [Feature]-Spec.md (comprehensive, 300-600+ lines OK)
├── work/
│   └── [Feature]-Work.yaml (planning doc)
└── stories/
    ├── [Feature].1-section.md (60-120 lines)
    ├── [Feature].2-section.md (60-120 lines)
    └── [Feature].3-section.md (60-120 lines)

Example:

3.1-Dog-Calendar-Booking/
├── 3.1-Dog-Calendar-Spec.md (comprehensive spec)
├── work/
│   └── 3.1-Dog-Calendar-Work.yaml
└── stories/
    ├── 3.1.1-header.md
    ├── 3.1.2-week-overview.md
    └── 3.1.3-leaderboard.md

When to use:

Design and development work
Complex features broken into sections
Agent implements piece-by-piece

Pattern 3: Reference Guide (Best for lookup)

Structure:

topic/
└── TOPIC-GUIDE.md (comprehensive, 200-400+ lines OK)

Example:

agentic-development/
├── AGENTIC-DEVELOPMENT-GUIDE.md (complete system overview)
├── CREATION-GUIDE.md (detailed technical reference)
└── PROTOTYPE-ANALYSIS.md (case study)

When to use:

Best practices documentation
Technical reference
Analysis and case studies
Agents look up specific sections as needed

🎯 File Type Decision Tree

Is this file sequential instructions?
├─ YES → Keep under 150 lines
│   └─ Over 150? → Split into router + phases
│
└─ NO → Is it a specification or reference?
    ├─ Specification → Length OK (will be broken into stories later)
    └─ Reference Guide → Length OK (agents reference specific sections)

✅ Post-File Checklist

After creating or updating any instruction file, check:

Step 1: Identify File Type

❓ Sequential instructions? (agent reads top-to-bottom)
❓ Specification? (will be broken down later)
❓ Reference guide? (agent looks up sections)

Step 2: Check Line Count

Sequential instructions over 150 lines? → Consider splitting
Multiple distinct phases? → Split into separate files
More than one job? → Split by responsibility

Step 3: Verify Organization

One clear purpose per file?
Natural break points if sequential?
Clear navigation if split?

Step 4: Suggest Improvements

If file should be split, suggest:

"Micro-step check: This file is [X] lines. Since it contains [Y distinct phases/sequential steps], I recommend splitting it into:

[router-file].md (overview + links)

[step-1].md (phase 1)

[step-2].md (phase 2) ...

Would you like me to split it now? (Y/N)"

📊 Size Reference Table

File Type	Ideal Size	Max Size	Split If...
Router/Overview	50-100 lines	120 lines	Multiple routing paths
Micro-step instructions	60-150 lines	180 lines	Multiple phases
Dialog scripts	150-300 lines	400 lines	Multiple separate dialogs
Page specifications	No limit	Use judgment	N/A (broken into stories)
Reference guides	200-400 lines	600 lines	Multiple distinct topics
PRDs	No limit	Use judgment	N/A (reference doc)
Technical docs	200-400 lines	600 lines	Multiple separate systems

🚨 Red Flags

Split immediately if:

❌ Sequential instructions over 200 lines
❌ File contains 3+ distinct phases
❌ Agent must scroll extensively to follow
❌ Table of contents feels necessary
❌ You're thinking "this is getting long..."

Keep as-is if:

✅ Comprehensive specification document
✅ Reference guide with clear sections
✅ Will be broken into smaller work items
✅ Agents reference specific parts, not read sequentially

💡 Key Principles

One job per file - Each file has ONE clear purpose
Router pattern - Main file routes to specific instruction files
Digestible chunks - Keep sequential instructions under 150 lines
Just-in-time loading - Agent loads only what's needed for current phase
Specs can be long - They get broken down into stories/tasks later
References can be long - Agents look up specific sections as needed
Instructions must be short - Agents read them sequentially

🔄 The Workflow Pattern

Comprehensive Spec → Planning Doc → Micro-Step Stories → Implementation

Long Specification (500+ lines OK)
    ↓
    Analyzed and broken down
    ↓
Planning Document (work file, yaml)
    ↓
    Split into implementable chunks
    ↓
Story Files (50-150 lines each)
    ↓
    Agent follows one story at a time
    ↓
Incremental Implementation

This pattern ensures:

Comprehensive requirements captured upfront
Work broken into manageable pieces
Agents follow focused, digestible instructions
Quality maintained through approval gates

File naming: See FILE-NAMING-CONVENTIONS.md
Agent activation: See project-analysis/ workflow
Project structure: See .wds-project-outline.yaml

Remember: The goal is to make instructions easy for agents to follow and easy for humans to maintain! 🎯

7.9 KiB Raw Blame History

Instruction File Guidelines

📏 File Size Guidelines

Files That SHOULD Be Split (Sequential Instructions)

Files That CAN Be Long (Reference/Specification)

🗂️ File Organization Patterns

Pattern 1: Router + Micro-Steps (Best for workflows)

Pattern 2: Spec + Stories (Best for implementation)

Pattern 3: Reference Guide (Best for lookup)

🎯 File Type Decision Tree

✅ Post-File Checklist

Step 1: Identify File Type

Step 2: Check Line Count

Step 3: Verify Organization

Step 4: Suggest Improvements

📊 Size Reference Table

🚨 Red Flags

💡 Key Principles

🔄 The Workflow Pattern

📝 Related Guidelines

7.9 KiB

Raw Blame History