Skip to content

Project Structure

Every OpenLogos project follows a standard directory structure under the logos/ directory. This convention enables AI tools and team members to quickly locate resources.

project-root/
├── AGENTS.md # AI assistant instructions (auto-generated, root)
├── CLAUDE.md # Claude Code instructions (auto-generated, root)
│
├── logos/ # OpenLogos methodology assets (isolated namespace)
│ ├── logos.config.json # Project configuration
│ ├── logos-project.yaml # AI collaboration index
│ ├── .openlogos-guard # Active change lock (present while a proposal is active)
│ ├── .openlogos-sync.json # Stamp written by a successful `openlogos sync`
│ ├── .openlogos-runtime/ # Guard runtime state (ignored via the .gitignore managed block)
│ │
│ ├── resources/ # Development resource documents (current "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: Architecture & tech stack
│ │ │ ├── 2-scenario-implementation/ # Phase 3: Scenario docs (sequence diagrams)
│ │ │ └── 3-deployment/ # Phase 3: Deployment plan + smoke strategy
│ │ ├── api/ # Phase 3: OpenAPI YAML
│ │ ├── database/ # Phase 3: SQL DDL
│ │ ├── test/ # Phase 3: Test case specs (Markdown)
│ │ │ └── smoke/ # Smoke test cases (post-deployment)
│ │ ├── scenario/ # Phase 3: API orchestration tests (JSON)
│ │ ├── implementation/ # Phase 3: Implementation manifest
│ │ ├── verify/ # Phase 3: Test results + reports (JSONL + Markdown)
│ │ └── reference/ # Reference materials: requirement/, todolist/, code/, image/, temp/, note/
│ │
│ ├── skills/ # OpenLogos methodology Skills (Claude Code / OpenCode / Other targets)
│ │ ├── prd-writer/
│ │ ├── product-designer/
│ │ ├── code-implementor/
│ │ └── ...
│ │
│ ├── spec/ # Methodology specifications
│ │
│ └── changes/ # Change proposal workspace
│ ├── {change-name}/ # Active change proposal
│ │ ├── proposal.md
│ │ ├── tasks.md
│ │ ├── TEST_SLICE_MANIFEST.json # Written by `openlogos slice plan`
│ │ └── deltas/
│ └── archive/ # Completed change history
│
└── src/ # Source code (structure determined by tech stack)

All OpenLogos methodology assets live under logos/, completely separated from the project’s own code and configuration. AGENTS.md and CLAUDE.md remain at the project root because AI tools require instruction files there.

The unified entry point for all OpenLogos methodology assets. Contains configuration files, development resource documents, and change management.

Stores all development resource documents — the project’s current “source of truth”. Organized by the OpenLogos three-layer progression model:

SubdirectoryPhaseContent
prd/1-product-requirements/Phase 1: WHYRequirements docs, user stories, competitive analysis
prd/2-product-design/1-feature-specs/Phase 2: WHATFeature specs, information architecture, design standards
prd/2-product-design/2-page-design/Phase 2: WHATPage design docs + HTML prototypes
prd/3-technical-plan/1-architecture/Phase 3: HOWArchitecture overview, tech stack decisions
prd/3-technical-plan/2-scenario-implementation/Phase 3: HOWScenario docs (sequence diagrams + step descriptions)
prd/3-technical-plan/3-deployment/Phase 3: HOWDeployment plan, environment config, rollback strategy, smoke scope
api/Phase 3: HOWOpenAPI YAML spec files
database/Phase 3: HOWSQL DDL design files
test/Phase 3: HOWUnit + scenario test case specs (Markdown)
test/smoke/Phase 3: HOWPost-deployment smoke test cases (Markdown)
scenario/Phase 3: HOWAPI orchestration test cases (JSON, API projects only)
implementation/Phase 3: HOWImplementation manifest (code delivery tracking)
verify/Phase 3: HOWTest results (JSONL), acceptance report, smoke report, deployment report

Change proposal workspace. Each feature iteration or bug fix starts with a change proposal here, merged back into main documents after approval. See Change Management for details.

AI Skill files deployed by openlogos init or openlogos sync for Claude Code, OpenCode, and Other. Each skill is a subdirectory containing a SKILL.md file. Other hosts keep their Skills in their own locations: .cursor/skills/<name>/SKILL.md for Cursor, .agents/plugins/openlogos/skills/ for Codex, and the skills/ folder of the OpenLogos plugin under .zcode/plugins/openlogos/, .qoder/plugins/openlogos/, or .workbuddy/plugins/openlogos/. Multi-file Skill assets (such as ui-ux-pro-max) always live here.

Methodology specification files deployed by openlogos init. These define the rules that Skills and tools follow (workflow, test result format, directory conventions, etc.).

Project configuration file defining document module paths and matching patterns:

{
"name": "my-project",
"locale": "en",
"aiTool": "claude-code",
"description": "",
"documents": {
"prd": { "label": { "en": "Product Docs" }, "path": "./resources/prd", "pattern": "**/*.{md,html,htm,pdf}" },
"api": { "label": { "en": "API Docs" }, "path": "./resources/api", "pattern": "**/*.{yaml,yml,json}" },
"test": { "label": { "en": "Test Cases" }, "path": "./resources/test", "pattern": "**/*.md" },
"scenario": { "label": { "en": "Scenarios" }, "path": "./resources/scenario", "pattern": "**/*.json" },
"database": { "label": { "en": "Database" }, "path": "./resources/database", "pattern": "**/*.sql" },
"verify": { "label": { "en": "Verify Reports" }, "path": "./resources/verify", "pattern": "**/*.{jsonl,md}" },
"changes": { "label": { "en": "Change Proposals" }, "path": "./changes", "pattern": "**/*.{md,json}" }
},
"sourceRoots": { "src": ["src"], "test": ["test"] },
"verify": {
"result_path": "logos/resources/verify/test-results.jsonl"
},
"guard": {
"unversioned": ["node_modules/", "dist/"]
}
}
FieldTypeDescription
namestringProject name
locale"en" | "zh"Document language
aiToolstring | string[]AI tool(s): claude-code, opencode, codex, cursor, zcode, qoder, workbuddy, other, or all
lifecycle"initial" | "launched"Legacy project-level field, no longer written. Lifecycle is per module in logos-project.yaml; openlogos sync migrates old values
sourceRootsobjectSource and test roots (src, test)
documentsobjectDocument module definitions (path + glob pattern)
verify.result_pathstringCustom path for test results JSONL
guard.unversionedstring[]Paths kept out of version control. They are rendered into the .gitignore managed block and are outside guard protection. Manage them with openlogos ignore
guard.exemptstring[]Committed paths that can be written without a proposal. Defaults to logos/resources/reference/ and baseline-seed staging when omitted. Manage them with openlogos exempt

AI collaboration index file — see logos-project.yaml Specification for full details.

All design documents follow the <module>-<number-or-name>.<ext> naming pattern. The module prefix is the namespace that lets multiple modules coexist in the same directory without collision.

  • Single-module projects use core- as the default prefix (e.g., core-01-requirements.md)
  • Multi-module projects add new files with the new module’s prefix alongside existing ones — no subdirectories needed

openlogos status uses the <moduleId>- prefix to determine per-module phase completion. A phase is considered done for a module only when at least one file with that module’s prefix exists in the phase directory.

  • Format: <module>-{number}-{english-name}.md — e.g., core-01-requirements.md, admin-01-requirements.md
  • Numbers control display order
  • HTML prototypes: <module>-{number}-{name}-prototype.html
  • Scenario implementation: <module>-SXX-{english-name}.md — e.g., core-S01-user-register.md, admin-S08-dashboard.md
  • Scenario numbers are globally unique across all modules, maintained by scenario_counter.next_id in logos-project.yaml
  • Test case specs: <module>-SXX-test-cases.md — e.g., core-S01-test-cases.md
  • Split by domain: auth.yaml, payment.yaml, license.yaml
  • OpenAPI 3.0 YAML format
  • API files are typically shared across modules (no module prefix required)
  • Complete schema: schema.sql or split by domain: auth.sql, payment.sql
  • Database files are typically shared across modules (no module prefix required)
  • Split by scenario: S01-user-auth.json, S02-payment-flow.json
  • JSON format defining API orchestration sequences
  • Test results: test-results.jsonl (JSONL format, one case result per line)
  • Acceptance report: acceptance-report.md (auto-generated by openlogos verify)
  • Slice manifest: logos/changes/<slug>/TEST_SLICE_MANIFEST.json, written by openlogos slice plan; see TEST_SLICE_MANIFEST
  • See Test Results Format for the detailed format specification
DirectoryPurpose
logos/resources/image/Product image assets (screenshots, icons)
logos/resources/context/Additional AI context files
docs/User-facing documentation (deployment guides, user manuals)
scripts/Development scripts