english/.opencode/skills/project-organization/references/directory-patterns.md

Directory Patterns

Detailed patterns for each top-level category. See SKILL.md Rule 1 for overview.

Documentation (docs/)

Evergreen project documentation for humans and AI agents.

docs/
├── project-overview-pdr.md          # Product/project requirements
├── system-architecture.md           # Architecture & components
├── code-standards.md                # Coding conventions
├── codebase-summary.md              # Auto-generated structure overview
├── project-roadmap.md               # Milestones & progress
├── project-changelog.md             # Version history
├── design-guidelines.md             # UI/UX standards
├── deployment-guide.md              # Deploy procedures
├── journals/                        # Technical diary
│   └── {YYMMDD-HHmm}-{slug}.md     # Session reflections, decisions
└── decisions/                       # Architecture Decision Records
    └── {YYMMDD}-{slug}.md           # ADR documents

Rules:

• Evergreen docs: no date prefix, slug-only naming
• Journals: always timestamped, one per session/event
• ADRs: date-prefixed, sequential numbering optional
• Keep docs under 200 lines; split into subsections if needed

Plans (plans/)

Implementation plans, research, and agent communication.

plans/
├── {YYMMDD-HHmm}-{slug}/           # Timestamped plan folders
│   ├── plan.md                      # Overview (<80 lines)
│   ├── phase-{NN}-{name}.md         # Phase details
│   ├── research/                    # Research for this plan
│   │   └── researcher-{NN}-{topic}.md
│   └── reports/                     # Agent reports scoped to plan
│       ├── scout-report.md
│       ├── code-reviewer-report.md
│       └── tester-report.md
├── reports/                         # Standalone agent reports
│   └── {type}-{YYMMDD-HHmm}-{slug}.md
├── research/                        # Standalone research
│   └── researcher-{YYMMDD-HHmm}-{topic}.md
├── templates/                       # Reusable plan templates
│   └── {type}-template.md
└── visuals/                         # Generated diagrams/previews
    └── {slug}.{ext}

Report type prefixes: scout-, researcher-, brainstorm-, code-reviewer-, tester-, debugger-, planner-

Rules:

• Plan folders always timestamped
• Phase files: phase-{NN}-{name}.md with zero-padded numbers (01, 02...)
• Scoped reports go inside their plan folder
• Standalone reports go in plans/reports/
• plan.md: keep generic, under 80 lines, link to phase files

Tests (tests/)

Test suites mirroring source structure.

tests/
├── unit/                            # Unit tests
│   └── {module}.test.{ext}
├── integration/                     # Integration tests
│   └── {feature}.integration.{ext}
├── e2e/                             # End-to-end tests
│   └── {flow}.e2e.{ext}
├── fixtures/                        # Test data/fixtures
│   └── {name}.{ext}
└── helpers/                         # Shared test utilities
    └── {name}.{ext}

Rules:

• Mirror source directory structure where practical
• Use .test., .spec., .integration., .e2e. suffixes
• Fixtures: descriptive names, no dates
• Follow project's existing test convention if one exists

Scripts (scripts/)

Build, deploy, and utility scripts.

scripts/
├── {action}-{target}.{ext}          # e.g., prepare-release-assets.cjs
├── {category}/                      # Group if 5+ scripts
│   └── {action}-{target}.{ext}

Rules:

• Kebab-case, verb-first naming: generate-manifest.cjs, send-notification.py
• Group into subdirs only when 5+ scripts in same category
• Include shebang line for shell scripts
• No date prefixes (versioned in git)

Assets (assets/)

Media, branding, designs, and generated content.

assets/
├── images/                          # Static images, screenshots
│   └── {slug}.{ext}
├── videos/                          # Video files
│   ├── {slug}/                      # Multi-file: self-contained folder
│   │   ├── master.mp4
│   │   ├── scene-{NN}.mp4
│   │   └── captions.srt
│   └── {slug}.mp4                   # Single file: flat
├── designs/                         # UI/UX designs, mockups
│   └── {project}/
│       ├── mockup-{variant}.{ext}
│       └── exports/
├── branding/                        # Logos, brand assets
│   └── {name}-{variant}.{ext}       # logo-dark.svg, logo-icon.png
├── generated/                       # AI-generated content
│   └── {type}/                      # images/, audio/, text/
│       └── {YYMMDD-HHmm}-{slug}.{ext}
└── {custom-type}/                   # Project-specific categories
    └── ...

Rules:

• Single file → flat in category dir
• Multi-file → self-contained subdirectory
• Variants: append -{variant} suffix (not separate folders)
• Size variants: {name}-{width}x{height}.{ext}
• Platform variants: {name}-{platform}.{ext}
• Generated content: always timestamped
• Custom categories allowed for project-specific needs

Configuration (Root / .config/)

project-root/
├── .env                             # Environment variables (gitignored)
├── .env.example                     # Env template (committed)
├── .gitignore
├── .eslintrc.*                      # Linter config
├── tsconfig.json                    # TypeScript config
├── package.json                     # Node.js manifest
└── .config/                         # Optional: grouped configs
    └── {tool}.{ext}

Rules:

• Follow ecosystem conventions (package.json at root, not in .config/)
• .env files: never commit actual secrets, only .example templates
• Group into .config/ only if ecosystem supports it

Guides (guide/ or guides/)

User-facing reference documentation, tutorials.

guide/
├── {topic}.md                       # Reference docs
├── {topic}.yaml                     # Structured data
└── {category}/                      # Group by category if 5+ files
    └── {topic}.md

Rules:

• Evergreen naming (no dates)
• Flat structure unless 5+ files warrant categorization
• Self-documenting names: SKILLS.md, COMMANDS.md, ENVIRONMENT_RESOLVER.md