diff --git a/new-docs/README.md b/new-docs/README.md
new file mode 100644
index 0000000..10d199f
--- /dev/null
+++ b/new-docs/README.md
@@ -0,0 +1,60 @@
+# OpenAPI Rollun
+
+Этот документ описывает, как мы в компании работаем с OpenAPI
+технологией, какие у нас есть инструменты и правила.
+
+## Overview
+
+The OpenAPI Specification - это открытая спецификация. Документацию проэкта можно
+посмотреть тут - [OpenAPI Initiative a Linux Foundation Collaborative Project.](https://www.openapis.org/).
+
+Мы используем OpenAPI для:
+- того что бы следовать API first approach
+- разрабатывать самодокументируемые API
+- генерировать шаблонный код (api client, server stubs)
+
+Мы поддерживаем 2 платформы:
+- PHP (server + client)
+- TypeScript (server + client)
+
+## Contributing
+
+Изменения в спецификацию происходят в 2 этапа:
+1. Открыть issue с описанием проблемы, и всем необходимым материалом. [шаблон](./issue-template.md)
+2. Открыть pull request с описанием проблемы/ссылкой на issue, и всем необходимым материалом. [шаблон](./pr-template.md)
+
+## General workflow
+
+Для того, что бы разрабоать новый сервер, нужно:
+- Создать OpenAPI spec, используя наш модифицированный [Swagger Editor](#swagger-editor-docs)
+- Сгенерировать код для сервера с OpenAPI spec (контроллеры, DTOs и тд.) с помощью [generator](#server-stub-generator)
+- Добавить [openapi lint](#openapi-lint) в ваш CI/CD pipeline.
+- Реализовать методы, в сгенерированом коде.
+
+Для того, что бы начать работу с сервисом через его API, нужно:
+- Сгенерировать с OpenAPI spec клиентскую библиотеку с помощью [generator](#client-lib-generator)
+
+## Tools
+
+### Swagger Editor Docs - [doc](./tools/swagger-editor.md)
+
+### OpenAPI lint - [doc](./tools/openapi-lint.md)
+
+### Server stub generator
+
+- PHP - [docs](./server/php.md)
+- TypeScript - [docs](./server/ts.md)
+
+### Client Lib generator
+
+- PHP - [docs](./client/php.md)
+- TypeScript - [docs](./client/ts.md)
+
+## Quick Start
+
+Гайд с примерами кода/команд, которые нужны для ефективной работы
+с OpenAPI в нашей компании [link](./quick-start/README.md)
+
+ ## Cross platform testing
+
+TODO: продумать механизм тестирования разных манифестов, для всех поддерживаемых платформ
diff --git a/new-docs/client/php.md b/new-docs/client/php.md
new file mode 100644
index 0000000..30404ce
--- /dev/null
+++ b/new-docs/client/php.md
@@ -0,0 +1 @@
+TODO
\ No newline at end of file
diff --git a/new-docs/client/ts.md b/new-docs/client/ts.md
new file mode 100644
index 0000000..30404ce
--- /dev/null
+++ b/new-docs/client/ts.md
@@ -0,0 +1 @@
+TODO
\ No newline at end of file
diff --git a/new-docs/issue-template.md b/new-docs/issue-template.md
new file mode 100644
index 0000000..ad3f0ef
--- /dev/null
+++ b/new-docs/issue-template.md
@@ -0,0 +1,136 @@
+# (название проблемы)
+
+1. Описание проблемы
+
+Описание: TODO
+
+2. Пример манифеста, который не работает
+
+Шаблон манифеста -
+```yaml
+openapi: 3.0.0
+info:
+ version: "1"
+ title: Sample
+ description: Sample manifest to showcase issue
+servers:
+ - url: http://server.dev/openapi/Sample/v1
+paths:
+ /{namespace}/Entity:
+ get:
+ parameters:
+ - in: query
+ name: "status"
+ required: false
+ schema:
+ type: string
+ - in: path
+ name: "namespace"
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: entity
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EntityResult'
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResult'
+ '500':
+ description: Internal error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResult'
+ post:
+ parameters:
+ - in: path
+ name: "namespace"
+ required: true
+ schema:
+ type: string
+ requestBody:
+ description: ""
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Entity'
+ responses:
+ '201':
+ description: entity
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EntityResult'
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResult'
+ '500':
+ description: Internal error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResult'
+components:
+ schemas:
+ Message:
+ type: object
+ required:
+ - level
+ - text
+ properties:
+ level:
+ type: string
+ description: 'Message level (like in a logger)'
+ example: 'error'
+ text:
+ type: string
+ description: 'Message text'
+ example: 'Something wrong.'
+ context:
+ type: array
+ description: 'Message context (like in a logger)'
+ items:
+ type: string
+ ErrorResult:
+ type: object
+ properties:
+ messages:
+ type: array
+ items:
+ $ref: '#/components/schemas/Message'
+ Result:
+ allOf:
+ - $ref: '#/components/schemas/ErrorResult'
+ type: object
+ properties:
+ data:
+ type: object
+ EntityResult:
+ allOf:
+ - $ref: '#/components/schemas/Result'
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/Entity'
+ Entity:
+ type: object
+ required:
+ - id
+ - name
+ properties:
+ id:
+ type: string
+ example: '5f51f78ccaa4c'
+```
+
diff --git a/new-docs/pr-template.md b/new-docs/pr-template.md
new file mode 100644
index 0000000..52dc523
--- /dev/null
+++ b/new-docs/pr-template.md
@@ -0,0 +1,35 @@
+# (Название вашего предложения)
+
+1. Описание проблемы, которую решает предложение + пример манифеста, который не работает
+
+Описание: TODO
+
+2. Описание предлогаемых изменений + пример манифеста, который должен работать
+
+Описание: TODO
+
+3. Являются ли изменения 'breaking'? Если да, что не совместимо.
+
+Ответ: TODO
+
+4. Есть ли возможность добавить поддержку в серверные генераторы?
+
+TS: Да/Нет
+PHP: Да/Нет
+
+5. Есть ли возможность добавить поддержку в клиентские генераторы?
+
+TS: Да/Нет
+PHP: Да/Нет
+
+6. Есть ли возможность добавить поддержку в Swagger editor?
+
+Да/Нет
+
+7. Обновить документацию нужных модулей.
+- генератор php server - PR link/Изменения не требуются
+- генератор php client - PR link/Изменения не требуются
+- генератор ts server - PR link/Изменения не требуются
+- генератор ts client - PR link/Изменения не требуются
+- генератор swagger editor - PR link/Изменения не требуются
+- quick start - PR link/Изменения не требуются
diff --git a/new-docs/quick-start/README.md b/new-docs/quick-start/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/new-docs/server/php.md b/new-docs/server/php.md
new file mode 100644
index 0000000..30404ce
--- /dev/null
+++ b/new-docs/server/php.md
@@ -0,0 +1 @@
+TODO
\ No newline at end of file
diff --git a/new-docs/server/ts.md b/new-docs/server/ts.md
new file mode 100644
index 0000000..30404ce
--- /dev/null
+++ b/new-docs/server/ts.md
@@ -0,0 +1 @@
+TODO
\ No newline at end of file
diff --git a/new-docs/tools/openapi-lint.md b/new-docs/tools/openapi-lint.md
new file mode 100644
index 0000000..976ea51
--- /dev/null
+++ b/new-docs/tools/openapi-lint.md
@@ -0,0 +1 @@
+# OpenAPI lint
\ No newline at end of file
diff --git a/new-docs/tools/swagger-editor.md b/new-docs/tools/swagger-editor.md
new file mode 100644
index 0000000..f08397f
--- /dev/null
+++ b/new-docs/tools/swagger-editor.md
@@ -0,0 +1,5 @@
+# Swagger Editor
+
+**TODO: Swagger editor docs**
+
+**TODO: list of custom rules for OpenAPI specs**
\ No newline at end of file