Directory Convention

This specification defines the standard directory structure that all OpenLogos projects follow. A unified layout enables AI tools and team members to quickly locate resources.

Standard Project Structure

project-root/
├── AGENTS.md                   # AI assistant instructions (auto-generated)
├── CLAUDE.md                   # Claude Code instructions (auto-generated)
│
├── logos/                      # OpenLogos methodology assets
│   ├── logos.config.json       # Project configuration
│   ├── logos-project.yaml      # AI collaboration index
│   │
│   ├── resources/              # Development resource documents (source of truth)
│   │   ├── prd/                # Product documents
│   │   │   ├── 1-product-requirements/    # Phase 1: Requirements
│   │   │   ├── 2-product-design/
│   │   │   │   ├── 1-feature-specs/       # Phase 2: Feature specs
│   │   │   │   └── 2-page-design/         # Phase 2: Page designs + HTML prototypes
│   │   │   └── 3-technical-plan/
│   │   │       ├── 1-architecture/        # Phase 3-0: Architecture & tech stack
│   │   │       ├── 2-scenario-implementation/  # Phase 3-1: Scenario docs
│   │   │       └── 3-deployment/          # Phase 3-3: Deployment plan + smoke strategy
│   │   ├── api/                           # Phase 3-2: OpenAPI YAML
│   │   ├── database/                      # Phase 3-2: SQL DDL
│   │   ├── test/                          # Phase 3-4a: Test case specs (Markdown)
│   │   │   └── smoke/                     # Smoke test cases (post-deployment)
│   │   ├── scenario/                      # Phase 3-4b: API orchestration tests (JSON)
│   │   ├── implementation/                # Phase 3-5: Implementation manifest
│   │   ├── verify/                        # Phase 3-6: Test results + reports
│   │   └── reference/                     # Reference materials (images, context)
│   │
│   ├── skills/                 # AI Skills (SKILL.md per skill, 16 built-in)
│   │   ├── prd-writer/
│   │   ├── deployment-designer/
│   │   ├── ui-ux-pro-max/
│   │   └── ...
│   │
│   ├── spec/                   # Methodology specifications (13 files)
│   │
│   └── changes/                # Change proposal workspace
│       ├── {change-name}/      # Active change proposal
│       │   ├── proposal.md
│       │   ├── tasks.md
│       │   └── deltas/
│       └── archive/            # Completed change history
│
└── src/                        # Source code (structure determined by tech stack)

Directory Responsibilities

logos/resources/prd/3-technical-plan/3-deployment/

Deployment plan documents. Contains deployment topology, environment configuration, release commands, rollback strategy, and smoke test scope definition.

• File naming: <module>-01-deployment-plan.md
• Written by: deployment-designer Skill (Phase 3 Step 3)

logos/resources/test/smoke/

Post-deployment smoke test case specifications. Contains SMOKE-* case IDs that openlogos smoke validates against.

• File naming: <module>-smoke-test-cases.md
• Written by: test-writer Skill (consuming deployment-designer output)

logos/resources/implementation/

Implementation manifest tracking code delivery status.

• File naming: implementation-manifest.md
• Written by: code-implementor Skill (Phase 3 Step 5)

logos/resources/reference/

Reference materials — screenshots, architecture diagrams, context files that AI reads but doesn’t generate.

logos/resources/verify/

Verification artifacts:

File	Description
test-results.jsonl	Runtime test results (UT/ST)
acceptance-report.md	Generated by openlogos verify
smoke-results.jsonl	Runtime smoke results
smoke-report.md	Generated by openlogos smoke
deployment-report.md	Generated by deployment executor

File Naming Conventions

Module Prefix Rule

All design documents follow: <module>-<number-or-name>.<ext>

• Single-module projects use core- as default prefix
• Multi-module projects add files with new module prefix alongside existing ones

Document Files

<module>-{number}-{english-name}.md — e.g., core-01-requirements.md

Scenario Files

<module>-SXX-{english-name}.md — e.g., core-S01-user-register.md

Scenario numbers are globally unique across all modules.

Test Case Files

<module>-SXX-test-cases.md — e.g., core-S01-test-cases.md

Deployment Files

<module>-01-deployment-plan.md — e.g., core-01-deployment-plan.md

Smoke Test Files

<module>-smoke-test-cases.md — e.g., core-smoke-test-cases.md

Stored in logos/resources/test/smoke/.

Related

• Project Structure — Configuration file formats and field definitions
• Module Naming Convention — Detailed module prefix rules
• logos-project.yaml — AI collaboration index schema